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Preface 


Intended Audience 

This document describes VMS RMS control blocks and services for 
programmers. 


Document Structure 

This document consists of three parts and two appendixes. 

• Part I contains general information in four sections: 

— Chapter 1 introduces the reader to VMS RMS functions and 
associated control blocks. 

— Chapter 2 discusses the VMS RMS program interface that applies to 
using any VAX programming language. 

— Chapter 3 describes the program interface with VAX MACRO, 

including how to use VMS RMS macros. This information will also be 
of interest to advanced programmers using other VAX programming 
languages. 

— Chapter 4 describes the groups of VMS RMS services and provides 
VMS RMS example programs using VAX MACRO. 

• Part II describes the VMS RMS control blocks and their associated fields, 
in Chapter 5 through Chapter 18. This information is intended for a 
programmer using any VAX programming language. 

• Part III describes the VMS RMS services, including the control block fields 
accessed by each service. This information is intended for a programmer 
using any VAX programming language. 

• Appendix A lists VMS RMS messages. 

• Appendix B contains the formats and associated usage notes for the VMS 
RMS control block initialization and store macros used by VAX MACRO 
programmers. Note that this material was formerly located in Part III. 


Associated Documents 

The following documents contain information related to this reference 

manual: 

• The Introduction to VMS System Routines and the VMS System Services 
Volume contain information about the calling routines on a VMS system. 

• The Guide to VMS File Applications contains related information about 
VAX RMS, FDL, and the use of files. 

• The VMS Networking Manual discusses the support of VMS RMS options 
for remote file access to non-VMS systems. For example, when the 
remote system is a PDP-11 system running RMS-11, Prolog 3 index files 
are not supported and some VMS RMS key definition XAB fields, as well 
as other control block fields, are not fully supported. 
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Preface 


Conventions 



For additional information about remote file access between VMS systems, 
see the VMS f/O User’s Reference Volume. 


Convention 

I RET I 


CTRL/C 


$ SHOW TIME 
05-JUN-1988 11:55:22 

$ TYPE MYFILE.DAT 


input-file, . . . 


[logical-name] 


quotation marks 
apostrophes 


Meaning 

In examples, a key name (usually abbreviated) 
shown within a box indicates that you press 
a key on the keyboard; in text, a key name is 
not enclosed In a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key Is not usually shown In syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 

A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 
box. 

In examples, system output (what the system 
displays) is shown in black. User input (what 
you enter) Is shown in red. 

In examples, a vertical series of periods, or 
ellipsis, means either that not all the data that 
the system would display in response to a 
command Is shown or that not all the data a 
user would enter is shown. 

In examples, a horizontal ellipsis indicates 
that additional parameters, values, or other 
Information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 

Brackets Indicate that the enclosed item is 
optional. (Brackets are not, however, optional 
in the syntax of a directory name In a file 
specification or in the syntax of a substring 
specification in an assignment statement.) 

The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (') Is used to refer to a single 
quotation mark. 
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Preface 


Convention Meaning 

lowercase letters and words Lowercase letters and words used in format 

statements in this manual represent information 
that you must supply. Such lowercase 
information may contain hyphens for readability. 
The accompanying text defines the information 
to be supplied. For example: 


uppercase letters and words 


window-size 

address 

Uppercase letters and words, equal signs ( = ), 
angle brackets ( <> ), and dollar signs ($) 
must be coded as shown. For example: 


RAT=<BLK.CR> 

.$0PEN 

Information enclosed within braces indicates 
that you may choose any one of the enclosed 
values. 

FIX 
STM 
STMCR 
STMLF 
UDF 
VAR 
VFC 


For example: RFM= 
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Convention 

Meaning 

(] 

Arguments enclosed within square brackets are 
optional, but if an optional argument other than 
a trailing optional argument is omitted, you must 
include a place holder for the omitted argument. 
This rule is shown syntactically below: 


$0PEN INFAB [.[ERR] [.SUC]] 


If you use either or both of the optional 
arguments, you must include the comma shown 
In the outside set of brackets. This comma 
acts as a delimiter between the first and second 
arguments when you use the second argument. 
When you omit the second argument and use 
the third argument, this comma acts as a place 
holder for the omitted argument. If you do not 
use either of the optional arguments, you can 
omit the comma. 


Here is an example of an instance in which the 
first optional argument is used and the second 
is omitted: 


$0PEN INFAB,ERR 


Here Is an example of an instance in which the 
second optional argument is used and the first 

Is omitted: 


$0PEN INFAB.,SUC 


Here is an example of an instance in which only 
the required argument is used: 


$0PEN iNFAB 
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New and Changed Features 


• Enhancements to the DAP/FAL interface 

DAP and FAL are the components of VMS RMS that extend record and 
file access through the network. The new features provide you with 
information about accessing files and records across a network including 
parameters that affect performance, functionality with other VMS systems, 
and functionality with non-VMS systems. 

To implement the enhancements, you open a file with a new XAB called 
the XABITM. You declare a XABITM in the same manner as other XABs 
and you select the appropriate features by means of fields within the 
XABITM structure. 

Most of the network file access controls are implemented explicitly 
through XABITM in conjunction with either the $CREATE service or the 
$OPEN service. Informational functions are implemented explicitly with 
the $DISPLAY service and implicitly with $CREATE and $OPEN. 

• Performance monitoring enhancements 

You can also use the XABITM to gather RMS performance statistics by 
way of the Monitor Utility. To gather statistics for an RMS file, you must 
create the file with a XABITM that enables statistics by way of the related 
item list. You can also enable statistics gathering from either the FDL 
or the DCL interface. If statistics gathering is enabled, it can only be 
disabled from DCL. 

• Enhancements to RMS multinational keys 

The enhancements to the RMS multinational key functions provide a way 
to use alternative (non-ASCII) collating sequences. The multinational 
key enhancements are based on the National Character Set Utility that 
permits you to define alternative collating sequences for special characters 
and to establish and maintain libraries of collating sequences. This 
eliminates having to redefine an alternative collating sequence when the 
application requires it. For information on NCS, see the VMS National 
Character Set Utility Manual 

The use of multinational keys requires the setting up of user-specified 
collating sequences for multinational characters on a per-key basis. With 
these collating keys, a record field can be sorted according to several 
languages where each language has its own key of reference. 

• Enhanced Asynchronous Interface 

The FAB$V_ASY option has been added to the VMS RMS asynchronous 
interface to support file operations. File operations and record operations 
can request notification of the synchronous completion of asynchronous 
operations with the FAB$V_-SYNCSTS option or the RAB$V_SYNCSTS 
option, respectively. 










General Information About VMS Record 
Management Services 

Part I introduces the reader to general mechanisms and conventions 
associated with VMS Record Management Services (VMS RMS). It 
discusses the following topics: 

• Argument passing 

• Control blocks 

• Symbols defined by VMS RMS 

• Invoking VMS RMS services 

• VMS RMS macros used by VAX MACRO programs 

• Syntax conventions for VAX MACRO 

• Example programs in VAX MACRO 
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Introduction to VMS RMS 


This section presents an overview of the general functions available through 
VMS Record Management Services (VMS RMS). It also briefly describes the 
VMS RMS services and control blocks. Unless otherwise stated, the term 
RMS refers to VMS RMS. 






1.1 VMS RMS Functions 

VMS RMS is a set of generalized services that assist application programs in 
processing and managing files and their contents. VAX MACRO programs 
can invoke these services by using the corresponding macros supplied in 
the system library SYS$LIBRARY:STARLET.MLB. (VMS RMS automatically 
searches this library for unresolved references when you assemble a source 
program.) Other VAX languages may support a similar means of invoking 
VMS RMS services. 

Although VMS RMS supports unit-record devices, such as terminals and 
printers, it primarily provides a comprehensive software interface to mass 
storage devices, such as disk and magnetic tape drives. 

VMS RMS provides a variety of disk file organizations, record formats, and 
record access modes from which you can select the processing techniques 
best suited to your application. VMS RMS supports sequential, relative, and 
indexed file organizations, and fixed-length and variable-length record formats 
are supported for each file organization. (Relative and sequential files also 
support other record formats.) The VMS RMS record access modes permit 
you to access records within these files sequentially, directly by key value, 
directly by relative record number, or directly by record file address (RFA). 
VMS RMS also provides a means of performing block I/O operations to 
support users with certain performance-critical applications (such applications 
may require user-defined file organizations and/or record formats). 

VMS RMS ensures safe and efficient file sharing by providing 

• Multiple file access modes, to allow file sharing to be consistent with the 
file operations 

• Automatic record locking in applicable file access modes, to ensure data 
integrity during record updates 

• Optional buffer sharing by multiple processes accessing the same file, to 
minimize I/O operations 

VMS RMS also enforces the security requirements of a multiuser system with 
potential multinode access by restricting file access to one or more user UIC 
types and to a list of user names. 

For systems that support DECnet network capabilities, VMS RMS provides 
a subset of file and record management services through the Data Access 
Protocol (DAP) to remote network nodes. Network DAP remote file 
operations are generally transparent to application programs. 
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1.2 Passing Arguments to VMS RMS 

The flexibility inherent in VMS RMS would require application programs to 
pass a multitude of arguments to perform such common operations as file 
creation and access. To eliminate the potential problems associated with 
passing numerous arguments for each service call, the application program 
places the arguments in one or more data control blocks before it invokes any 
VMS RMS service. The only argument required to invoke most VMS RMS 
services is the symbolic address of the appropriate data control block. 


1.2.1 VMS RMS Services and Control Blocks 

Because VMS RMS operates on files and records, its services generally fall 

into one of two groups: 

• File services that create and access a new file, access (open) an existing 
file, extend the disk space allocated to a file, close a file, obtain file 
characteristics, and perform other functions related to files 

• Record services that get, find (locate), put (insert), update, and delete 
records, and perform other operations not directly related to record I/O, 
such as associating one or more record streams (methods of accessing 
records) with an open file 

To support service operations, VMS RMS provides two types of control 

blocks: 

• Control blocks that provide file-related arguments to VMS RMS file 
services 

• Control blocks that provide record-related arguments to VMS RMS record 
services 


1.2.2 Control Blocks for File Services 

File services use a control block called the file access block (FAB). When 
creating a file, the user must store arguments in the FAB that define the 
file characteristics, the file specification, and certain run-time access options. 
When your process opens an existing file, the FAB specifies only the file 
specification and the run-time access options. 

There are three categories of FAB arguments and the following list briefly 
introduces each: 

• File specification arguments identify primary and default file 
specifications used at run-time to locate the file. 

• File characteristics arguments specify the file organization, record type, 
allocation information, and other information. 

• Run-time access options specify the operations that can be done by 
the initiating process and the operations that can be done by sharing 
processes, a variety of file-processing options, and the address (or 
addresses) of one or more control blocks whose fields supplement or 
supersede the information in the FAB. 
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The two types of optional control blocks that can supplement or supersede 
the information in the FAB are the name block (NAM) and the extended 
attribute block (XAB). 

The NAM block supplements the file specification information available in 
a FAB. It is especially useful for locating and opening files when the file 
specification is entered by an interactive user or when a file specification 
includes a wildcard character or a search list logical name representing 
multiple files. 

There is only one type of NAM block, and you usually associate only one 
NAM block with a file. To provide an extra level of defaults for a file 
specification, however, VMS RMS will apply defaults using additional NAM 
blocks that contain the file specifications of related files. 

A XAB usually supersedes and supplements the file characteristics specified 
in the associated FAB and multiple XABs may be used to support a single 
file. There are several types of XABs, each of which is used for a different 
purpose. Each type of XAB has a 6-letter mnemonic name consisting of 
the prefix "XAB" followed by a 3-letter mnemonic that relates to the XAB 
function. For instance, the XAB that supplements and supersedes the file 
allocation information in the FAB is called an allocation control XAB, or 
XABALL. 

The XABs used for file operations are briefly described in the following list: 

• Allocation control XAB (XABALL)—allows greater control over disk file 
allocation and positioning during file allocation. 

• Date and time XAB (XABDAT)—specifies date and time values for backup, 
creation, expiration, and revision times, and the revision number. 

• File header characteristic XAB (XABFHC)—receives the file characteristics 
information contained in the file header block. 

• Item list XAB (XABITM)—provides a convenient means for using item 
lists to pass information between RMS and the application program. 

• Journaling XAB (XABJNL)—supports file journaling operations. 

• Key definition XAB (XABKEY)—defines the key characteristics to be 
associated with an indexed file. 

• File protection XAB (XABPRO)—defines file protection characteristics 
that specify what class of users or list of users can have certain specified 
access rights. For ANSI magnetic tape files using HDRl labels, this XAB 
specifies the accessibility field character. 

• Revision date and time XAB (XABRDT)—specifies the revision date and 
time value and the revision number associated with a file. 

• Recovery unit XAB (XABRU)—supports the use of recovery units to 
assure data file integrity. 

• Summary XAB (XABSUM)—stores additional file characteristics associated 
with an indexed file. 
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1.2.3 Control Blocks for Record Services 

Record services use a control block known as the record access block, or RAB. 
Some of the arguments the user must store in the RAB include the address of 
the related FAB, the address of input and output record buffers, the type and 
size of general I/O buffers, whether a file's records will be accessed directly 
or sequentially, certain tuning options, and other information. 

An extended attribute block (XAB) can both supersede and supplement the 
record characteristics specified in the RAB. As with a XAB that supersedes 
and supplements a FAB, a XAB that supersedes and supplements a RAB has 
a 6-letter mnemonic name consisting of the prefix "XAB" followed by three 
letters. Note that there are only two XAB types for record operations, the 
terminal XAB (XABTRM) and the recovery unit XAB (XABRU). 

The XABTRM defines the symbolic address and length of a user-supplied 
argument list that defines the terminal operation and provides more flexibility 
than using RAB fields. 

See the VAX RMS Journaling Manual for details relating to the use of the 
XABRU. 


1.2.4 The Dual Purpose of Control Blocks 

Control blocks provide input to VMS RMS services and they provide output 
from VMS RMS services including the following run-time information: 

• Detailed file characteristics, including file organization, record format, and 
record size 

• Device characteristics 

• File, directory, and device identifiers 

• The address (location) and length of a requested record 

• Returned condition values 

For this reason, certain programs specifically allocate a NAM block or one 
or more XABs dedicated to receiving information returned by VMS RMS 
services. Typically, such information can be examined to determine how the 
file should be processed. 

In most cases, however, control blocks are used both to transmit and to 
receive information between the application program and VMS RMS and 
should not be located in a read-only program section. 

Be sure that control block fields not currently used by a particular service 
have valid default values because future versions of VMS RMS may use 
them. This applies also to control block fields that are currently described 
as "ignored for DECnet operations" because future versions of VMS RMS or 
DECnet may support those fields. 
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2 The Program Interface with VMS RMS 


This section introduces the application program interface with VMS RMS that 
is applicable to all VAX languages in terms of the following: 

• The VMS RMS run-time processing environment 

• VMS RMS symbol-naming conventions 

• The calling sequence for VMS RMS services 

• Allowable program execution modes 

• Condition values returned by VMS RMS services 


2.1 The Run-Time Environment and VMS RMS Programming 

The VMS RMS run-time processing environment consists of a set of blocks 
and the run-time services. The control block fields accessed by each service 
specify to VMS RMS the appropriate file and record operations. Depending 
on the operation, VMS RMS uses one or more control blocks by referring to 
one or more fields as input to, or output from, the operation. 

To use VMS RMS, you must do the following: 

1 Allocate the appropriate control block, usually at assembly time or 
compilation time. Control blocks must not reside in read-only storage 
and should be aligned on a longword boundary to maximize efficiency. 

2 Insert the appropriate values into the control block fields before you 
invoke the related service. 

3 Invoke the appropriate VMS RMS service. As part of this step, a 
condition value should always be examined. 

To perform advanced VMS RMS functions, you may need to set various 
control block field values at run time between the time the file is opened and 
when the VMS RMS service is invoked. 

Note that VAX languages perform some of these steps transparently when a 
particular language statement or macro is present in a source program. 

Two fields in each control block, the block length (BLN) field and the block 
identifier (BID) (or block code (COD) field in a XAB), define the length of 
the control block (in bytes) and identify the control block type, respectively. 
These internal VMS RMS fields are always used as input arguments by the 
VMS RMS service that accesses the control block and must be set before 
the control block can be used. The fields are initialized automatically by 
the appropriate VAX MACRO assembly-time initialization macro and must 
contain the correct value for the type of control block. After the block length 
and block identifier fields are established, you must treat them as read-only 
fields until the control block is no longer needed. 

Part II describes each control block field in detail, including its length and its 
symbolic name. 
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2.1 The Run-Time Environment and VMS RMS Programming 


Appendix B lists the VAX MACRO calling format for each VAX MACRO 
control block macro. 

Part III lists the calling format for each service together with the input control 
block fields and the output control block fields for each service. 


2.2 Conventions for Naming Fields 

VMS RMS uses mnemonic names to identify control block fields. For 
example, the mnemonic name for the FAB allocation quantity field is ALQ. 

The mnemonic name (usually consisting of three characters) serves as a suffix 
to a symbolic name that identifies the location of each control block field. 

You should use the symbolic names to be sure you place values in the correct 
control block fields. VMS RMS defines each symbolic name as a constant 
value equal to the offset, in bytes, from the beginning of the control block to 
the beginning of the field. These field names are thus called symbolic offsets. 

Symbolic offset names are defined when the appropriate VAX MACRO control 
block initialization macro is used, when the appropriate VAX MACRO control 
block symbol definition macro is used, and when some VAX languages invoke 
VMS RMS. Alternatively, all control block symbolic offset names are available 
when you use the VAX MACRO $RMSDEF macro in a VAX MACRO program 
or procedure. 

The format of the symbolic offsets consists of a 3-letter control block identifier 
(FAB, NAM, XAB, or RAB), a dollar sign ($), a 1-letter indicator of the length 
of the field (B, W, L, Q, or T), an underscore (.>), and the field mnemonic, 
which is usually three letters. 

The general format of the symbolic offset is shown in the following example: 
ccc$x_fff 

The components of the symbolic offset format are summarized in the 
following table. 
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Component 

Length 

Description 

ccc 

3 letters 

Identifies the type of control block: 
FAB, NAM, XAB (for all XABs), or 
RAB. 

$ 

1 character 

Separates the control block 
identifier from the field length 
identifier; a dollar sign ($). 

X 

1 letter 

Identifies the length of the field; 

B for byte, W for word, L for 
longword, Q for quadword, T for 
text buffer address. Symbolic 
length fields are identified by 
the letter S in this position. For 
example, the value field XAB$S_ 
CACHE_TMO specifies the number 
of bytes allocated for defining the 
value of the cache timeout. See 
text for exceptions. 

— 

1 character 

Separates the field length Identifier 
from the field name; always an 
underscore (_). 

fff 

3 or more letters 

Identifies the mnemonic name 
of the field, which Is used in the 
VAX MACRO control block macro. 
Some mnemonics contain more 
than three letters; for example, 
symbolic offset XAB$B_PROLOG 
(from XABKEY). 


For example, the FAB field whose mnemonic is ALQ has a length of one 
longword and is identified by the symbolic offset FAB$L_ALQ. The field 
NAM$L_RLF is a NAM longword field whose mnemonic RLF reflects its 
name, the related file field. 

Exceptions to the length designation are NAM$W_DID, NAM$W_FID, 
XAB$W__RFI, and RAB$W__RFA. These symbolic offsets mark the locations of 
fields that are three words, not one word. 

The length of a T field is specified by the corresponding S field; for example, 
the length of the NAM$T__DVI field is specified by the symbolic value field 
named NAM$S--DVI. 

When a control block field contains options identified by bits, each valid bit 
location has a symbolic offset name. Certain control block fields are binary 
options fields consisting of bit values. For these bits in a binary options field, 
the format of symbolic names resembles the format of the field names, except 
for the length indicator. Instead of identifying the field length, which is 
always one bit, the length field indicates whether a mask value (M) or bit 
offset (V) is defined by the symbolic name, as described below. 
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Format Description 


xxx$M_fff Indicates a mask value in a binary options field, typically where 
multiple bit options can be chosen. Used to set or clear bit 
values. 

xxx$V_fff Indicates the symbolic bit offset (number of bits from the 

beginning of the binary options field). Used to test bit values or 
to set bit values. 


The XXX identifies the control block (FAB, NAM, XAB, or RAB); the $ and _ 
are separator characters, and the fff defines the mnemonic for the bit option. 
For example, the option CTG in the FAB file-processing options (FOP) field 
has a symbolic bit offset of FAB$V_CTG and a mask value of FAB$M_CTG. 

Another type of field can contain only certain values; thus there are no mask 
values or symbolic bit offsets. Unlike a binary options field, each possible 
value is identified by a symbolic constant value, in the following form: 

xxx$C_fff 

Note that the letter C replaces the letter M, denoting that this field is a 
constant (keyword) value field, not a mask value field. For example, the 
file organization (ORG) field of the FAB (FAB$B_ORG) can only contain 
the values FAB$C_IDX (indexed), FAB$C_REL (relative), or FAB$C_SEQ 
(sequential). In some instances, the letter K is used to denote a constant 
(keyword) value field in place of the letter C; otherwise, the naming 
convention is the same. 

When specifying control block field locations, avoid using actual byte 
displacement values to identify control block field locations; instead, use the 
supplied symbolic offsets. VMS RMS control block field locations may not 
always be the same from release to release of VMS; however, the symbolic 
offset names that identify the field locations always identify the same fields. 


2.3 The VMS RMS Calling Sequence 

VMS RMS uses the standard VAX calling sequence and conventions, and 
preserves all general registers across a call, except for register 0 (RO) and 
register 1 (Rl). When the service completes execution, it returns control to 
the calling program, passing a condition value in RO. You should analyze the 
completion value to determine the success or failure of the service and to alter 
the flow of execution of your program, if necessary. Where applicable, you 
should use the STS field and the STV field of the appropriate control block 
for signaling errors, instead of RO. For additional information about VMS 
RMS completion values, see Section 2.4. 

When calling a VMS RMS service, you must provide an argument list to 
specify the associated control block (FAB or RAB) and, optionally, any 
completion routines. The argument list is from two to four longwords in 
length, as shown in Figure 2-1. (The Rename service, however, uses a 
5-longword argument list.) 
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Figure 2-1 Argument List Format 


31 

8 

7 0 

reserved 

argument count 

control block address 


error completion routine address 



success completion routine address 



optional 


VMS RMS interprets the fields in the argument list as follows: 

• The argument count field contains a binary value, from 1 through 3, 
representing the number of arguments in the argument list. For the 
Rename service only, set this value to 4. 

• The control block address field contains the address of either the FAB (for 
file operations) or the RAB (for record operations). 

• The error completion routine address field optionally contains the address 
of the entry mask of a user-written completion routine to be called if the 
requested operation fails. If used, the completion routine executes as an 
asynchronous system trap (AST). 

• The success completion routine address field optionally contains the 
address of the entry mask of a user-written completion routine to be 
called if the requested operation completes successfully. If used, the 
completion routine executes as an asynchronous system trap (AST). 

• The new FAB address field (not shown in Figure 2-1) contains the address 
of the FAB that contains the new file name for the Rename service. This 
field must be present only for the Rename service. 


Condition Values 


Before returning to your program from a file or record operation, VMS RMS 
indicates the success or failure of the operation by setting a condition value in 
the completion status code field (STS) of the associated control block (FAB or 
RAB). 

When first returning to your program after a call to an operation, VMS 
RMS also sets general register 0 to the value in the status code field. In 
asynchronous operations, register 0 may simply indicate that the operation 
has been initiated. 

In general, you may receive one of many error or success codes from an 
operation. (The discussion of each VMS RMS service in Part III includes a 
list of the possible condition values that you can receive.) (See Appendix A 
for a complete list of all VMS RMS status codes.) You should test for success 
by checking only the low-order bit of the status code for a true condition (bit 

2-5 











The Program Interface with VMS RMS 

2.4 Condition Values 


001 

(1) 

oil 

(3) 

000 

(0) 

010 

(2) 

100 

(4) 

The 

usual 


set). The three low-order bits returned in the status code indicate the severity 
of the code. The severity codes are as follows: 

Success (low-order bit set). 

Information (low-order bit set). 

Warning; indicates a nonstandard condition. The operation may 
have performed some, but not all, of the requested function. 

Error; you must recognize that a problem exists and provide a 
contingency plan in your program for such a condition. 

Severe error; normally caused by program logic errors or other 
unrecoverable conditions. 


success, failure, or specific completion values. For certain completion values, 
VMS RMS returns additional information in the status value field (STV) of 
the control block. The description of the codes in Appendix A indicates the 
instances when the STV contains such information. 

The STS and STV fields should be used to signal VMS RMS errors to 
ensure that the error message includes all relevant information. For the 
file processing and file naming services, use the STS and STV fields of 
the specified FAB (use the old FAB for the Rename service). For record 
processing and block I/O processing services, use the STS and STV fields of 
the corresponding RAB. (Consult Table 3-2 if you are not sure of the group 
to which a particular VMS RMS service belongs.) 

The recommended way to signal VMS RMS errors is to provide both the STS 
and STV fields of the RAB or FAB as arguments to the Run-Time Library 
(RTL) routine LIB$SIGNAL (or LIB$STOP). Certain VAX languages provide 
a built-in means of signaling errors, such as by providing a system-defined 
function. For a more detailed explanation of condition signaling and invoking 
RTL routines, see the VMS Run-Time Library Routines Volume. 

VMS RMS services are considered system services for the purpose of 
generating system service exceptions on errors. You can choose whether 
to test and handle errors in your program or set the system service failure 
exception mode (using the Set System Failure Exception Mode system service, 
SYS$SETSFM) to have failures automatically signaled. For most applications, 
especially if a high-level language is used, testing and handling errors in 
your program is the preferred method. If you test for error conditions in 
your program, you should be sure to disable any unwanted system service 
exception generation. 

Note that if the FAB or RAB is invalid or inaccessible, then the error 
completion routine will not attempt to store the error code in the STS 
field of an invalid control block structure. The following errors can be 
detected only by testing RO (or by enabling system service failure exception 
mode), following the completion of a VMS RMS operation (even if an error 
completion AST has been specified): 


2-6 









2.5 



2.6 


The Program Interface with VMS RMS 

2.4 Condition Values 


RMS$_BLN 

RMS$_BUSY 

RMS$_FAB 

RMS$_RAB 

RMS$_STR 


Invalid block length field (either FAB or RAB) 

User structure (FAB/RAB) still in use 

FAB not writable or invalid block ID field 

RAB not writable or invalid block ID field 

User structure (FAB/RAB) became Invalid during operation 


These completion codes indicate that the FAB or RAB is invalid or 
inaccessible. These completion codes can only be detected and signaled 
using RO, but are usually rare and, if they occur at all, would most likely 
occur during initial program debugging and testing. Thus, you must examine 
the completion value in RO (instead of the STS field of the FAB or RAB) for 
the completion codes listed above. If necessary, your program could test for 
these errors and, if encountered, signal these completion values using RO 
instead of the STS and STV fields. 


Allowable Program Execution Modes 

Generally, VMS RMS executes in either executive mode or executive AST 
mode. When a VMS RMS operation is initiated, processing begins in 
executive mode. If device I/O is necessary to process the request, the $QIO 
system service is called. VMS RMS specifies an executive-mode AST to 
signal completion. At this point, VMS RMS exits from executive mode. If the 
operation is being performed asynchronously, control is returned to the caller; 
if the operation is synchronous, VMS RMS waits for an event flag in the 
access mode of the caller. When the I/O is complete, VMS RMS continues 
processing in executive AST mode. Thus, user-mode ASTs can be serviced 
while a synchronous VMS RMS operation called from user mode is awaiting 
I/O completion. However, processing in user mode during an asynchronous 
VMS RMS operation is interrupted by VMS RMS processing in executive AST 
mode when I/O completes. 

VMS RMS should not be called from kernel mode, from executive AST mode, 
nor from executive mode when executive-mode ASTs are disabled. 


Reserved Event Flags 

VMS RMS uses system-reserved event flags to synchronize its internal 
operations. VMS RMS reserves event flags 27, 28, 29, and 30 for possible 
use; in addition, event flag 31 is used to specify a "do not care" event flag for 
asynchronous processing. 
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DEC Multinational Character Set 

You can use any character in the DEC Multinational Character Set in VMS 
RMS records, including the key value of an indexed file. Keys are collated 
according to their corresponding character code value. 

For a list of characters in the DEC Multinational Character Set, see the VAX 
EDT Reference Manual. 
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3 VMS RMS Macros and VAX MACRO Programming 






This chapter describes the four types of VMS RMS macros used in VAX 
MACRO programming. It begins with a description of each of the four types 
of macros, macro naming conventions and macro syntax rules. The remainder 
of the chapter describes how to use the macros and includes examples for 
each of the four types. Note that in the remainder of Part I, the use of 
the term "macro" refers to a program macro written in the VAX MACRO 
language. 


VMS RMS Macros 

VMS RMS provides four types of macros used by VAX MACRO programs 
implementing VMS RMS features. The functions these macros provide are 
described below. 

• Control block initialization macros initialize a control block at assembly 
time. This type of macro performs five separate actions: 

— Allocates space within the program image for the specified control 
block 

— Defines the symbolic names associated with a control block 

— Initializes certain control block fields with internally used values 

— Initializes specified control block fields with user-specified values 

— Initializes certain fields with system-supplied defaults (does not apply 
to all control block macros) 

As an alternative to using this type of macro, an application program 
would have to allocate each control block needed with its correct 
length, initialize the internally used fields with the correct values, 
and initialize or set user-specified values in the appropriate fields. It 
is strongly recommended that the supplied macros be used for VAX 
MACRO programs. 

• Control block symbol definition macros define control block symbolic 
names at assembly time without allocating and initializing the control 
block. These macros are needed only when the corresponding 
initialization macro is not used and the symbols are not defined by 
the VAX language used. 

• Control block store macros set (or reset) specified fields in a control block 
with user-specified values at run time. Alternatively, you can set values 
in control block fields at run time using VAX MACRO instructions, such 
as the MOVx and MOVAx instructions. Field locations are made available 
using the symbolic name assigned to each control block field to represent 
its offset from the start of the control block. 
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3.1 VMS RMS Macros 

• Service macros invoke VMS RMS services at run time. When a service 
is invoked, one or more control blocks are examined for required field 
values. Values are also returned in one or more control blocks, including 
condition codes. VMS RMS services conform to the VAX calling standard 
and thus can be invoked directly from any VAX language, if needed, 
without the calling program having to use the supplied macro. However, 
the appropriate control block must be present with the appropriate field 
values set for the requested operation. 

VMS RMS stores its macros for use by VAX MACRO programs in 

SYS$L1BRARY:STARLET.MLB. 


3.1.1 Conventions for Naming VMS RMS Macros 

The corresponding macro name that initializes each control block at assembly 
time consists of a dollar sign ($) followed by the name of the control block. 
Thus, the macro that initializes a FAB is called $FAB; the macro that initializes 
an XABALL is called $XABALL. 

The macros that define symbolic offsets without performing control 
block initialization contain the suffix "DEF" following the corresponding 
initialization macro name; for example, $FABDEF and $XABALLDEF. 

For the macros that set control block field values at run time, the name of the 
assembly time macro is followed by —STORE. Thus, the $FAB macro has a 
$FAB—STORE macro for setting FAB values at run time and the $XABALL 
macro has a $XABALL—STORE macro for setting XABALL values at run time. 

Table 3-1 summarizes the control blocks, their assembly time macro names, 
and their functions. 


Table 3-1 User Control Blocks 
Control Macro 

Block Names Function 


FAB 


NAM 


$FAB 

SFABDEF 

$FAB_STORE 


$NAM 


SNAMDEF 

$NAM_STORE 


Describes a file and contains file-related 
Information 

Allocates storage for a FAB and initializes 
certain FAB fields; also defines symbolic offsets 
for a FAB 

Defines symbolic offsets for a FAB 

Moves specified values into a previously 
allocated and initialized FAB 

Contains file specification information beyond 
that In the file access block 

Allocates storage for a NAM and initializes 
certain NAM fields; also defines symbolic 
offsets for a NAM 

Defines symbolic offsets for a NAM 

Moves specified values into a previously 
specified and allocated NAM 
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3.1 VMS RMS Macros 


Table 3-1 (Cont.) User Control Blocks 


Control 

Macro 


Block 

Names 

Function 

RAB 


Describes a record stream and contains record- 
related information 


$RAB 

Allocates storage for a RAB and initializes 
certain RAB fields; also defines symbolic offsets 
for a RAB 


$RABDEF 

Defines symbolic offsets for a RAB 


$RAB_STORE 

Moves specified values into a previously 
specified and allocated RAB 

XAB 


Contains file attribute information beyond that 
in the file access block; for XABTRM, contains 
information beyond that In the record access 
block 


$XABxxx' 

Allocates and initializes an XAB 


SXABxxxDEF 

Defines symbolic offsets for an XABxxx 


$XABxxx_STORE 

Moves specified values into a previously 
specified and allocated XABxxx 


^The variable xxx represents a 3-character mnemonic. 


VMS RMS services can be called from any VAX language using the VAX 
Procedure and Condition Handling standard. VMS RMS services are system 
services identified by the entry point prefix "SYS$" followed by three or 
more characters. In the corresponding VAX MACRO macro name, the "SYS" 
prefix is not used. For example, the Create service has an entry point of 
SYS$CREATE and a VAX MACRO macro name of $CREATE. A complete 
description of each service is provided in Part III. 

Table 3-2 describes the functions of each VMS RMS service, including the 
service entry point name and its corresponding VAX MACRO macro name. 


Table 3—2 VMS RMS Services 


Service Name 

Macro Name 

Description 

File Processing and File Naming Macros 

SYSSCLOSE 

SCLOSE 

Terminates file processing and disconnects 
all record streams 

SYSSCREATE 

SCREATE 

Creates and opens a new file of any 
organization 

SYS$DISPLAY 

$DISPLAY 

Returns the attributes of an open file to the 
application program 

SYSSENTER' 

SENTER 

Enters a file name Into a directory 

SYSSERASE 

$ERASE 

Deletes a file and removes its directory 
entry 


^This service is not supported for DECnet operations involving remote file access between 
two VMS systems. 
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3.1 VMS RMS Macros 


Table 3-2 (Cent.) VMS RMS Services 


Service Name 

Macro Name 

Description 

File Processing and File Naming Macros 

SYSSEXTEND 

$EXTEND 

Extends the allocated space of a file 

SYS$OPEN 

$OPEN 

Opens an existing file and initiates file 
processing 

SYS$PARSE 

SPARSE 

Parses a file specification 

SYS$REMOVE’ 

SREMOVE 

Removes a file name from a directory 

SYS$RENAME 

SRENAME 

Assigns a new name to (renames) a file 

SYSSSEARCH 

SSEARCH 

Searches a directory, or possibly multiple 
directories, for a file name 

Record Processing Macros 


SYS$CONNECT 

SCONNECT 

Establishes a record stream by associating 
a RAB with an open file 

SYSSDELETE 

SDELETE 

Deletes a record from a relative or indexed 
file 

SYSSDISCONNECT $DISCONNECT 

Terminates a record stream by 
disconnecting a RAB from an open file 

SYS$FIND 

$FIND 

Locates and positions to a record and 
returns Its RFA 

SYSSFLUSH 

SFLUSH 

Writes (flushes) modified I/O buffers and 
file attributes 

SYSSFREE 

$FREE 

Unlocks all records previously locked by the 
record stream 

SYS$GET 

$GET 

Retrieves a record from a file 

SYS$NXTVOL' 

SNXTVOL 

Causes processing of a magnetic tape file 
to continue to the next volume of a volume 

set 

SYS$PUT 

$PUT 

Writes a new record to a file 

SYS$RELEASE 

SRELEASE 

Unlocks a record pointed to by the contents 
of the RAB$W_RFA field 

SYSSREWIND 

SREWIND 

Positions to the first record of a file 

SYSSTRUNCATE 

STRUNCATE 

Truncates a sequential file 

SYSSUPDATE 

SUPDATE 

Rewrites (updates) an existing record In a 
file 

SYS$WAIT 

$WAIT 

Awaits the completion of an asynchronous 
record operation 


'This service is not supported for DECnet operations involving remote file access between 
two VMS systems. 
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3.1 VMS RMS Macros 


Table 3-2 (Cent.) VMS RMS Services 


Service Name 

Macro Name 

Description 

Block I/O Processing Macros 

SYSSREAD 

$READ 

Retrieves a specified number of bytes from 
a file, beginning on block boundaries 

SYSSSPACE 

$SPACE 

Positions forward or backward in a file to a 
block boundary 

SYS$WRITE 

$WRITE 

Writes a specified number of bytes to a file, 
beginning on block boundaries 


3.1.2 Applicable VAX MACRO Syntax Rules 

One of the conventions of VMS RMS control block macros is to use the 
mnemonic name associated with each field as a keyword to identify each 
argument. Using a keyword ensures the accuracy of argument value 
placement regardless of the ordering you use when you code the related 
argument. For example, the mnemonic keyword for the FAB field that 
specifies the allocation quantity is ALQ. Thus, when using the $FAB macro 
to initialize the allocation quantity field, you might use the following macro 
expression: 

INFAB: $FAB ALQ=500 

This macro statement defines the start of the FAB at label (symbolic address) 
INFAB and initializes the allocation field (at symbolic offset ALQ) to provide 
500 blocks of space to the file being created. 

In this instance, if you want to change the allocation value to 250 blocks at 
run time, you could use the following macro expression: 

MOVL #250, INFAB+FAB$L_ALG| ; Set allocation quantity 

In fields that contain binary options or keyword values, you should use the 
appropriate keyword or symbolic binary option value. For example, the FAB 
has a field at symbolic offset ORG that specifies the file organization. Three 
keywords are defined for this field; SEQ (sequential file), REL (relative file) 
and IDX (indexed file). To specify an indexed file organization, you should 
use the following macro expression: 

OUTFAB: $FAB 0RG=IDX 

To set this value at run time, you must move the formal title of the value into 
the formal title of the field: 

MOVAL OUTFAB, R5 ; Move address into R5 

MOVB #FAB$C_IDX. FAB$B_0RG(R5) ; Store constant value 

In control block macros, arguments for bit fields that can contain multiple 
values are usually enclosed within left angle ( <) and right angle (> ) 
brackets. Consider the file access (FAC) field (FAB$B_FAC) in the FAB, a bit 
field that can contain multiple values. To permit a process to do get and put 
operations, the following macro expression could be used: 

INFAB: $FAB FAC=<GET,PUT> ; Specify Put and Get operations 
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3.1 VMS RMS Macros 

Control block macro arguments that are interpreted as ASCII characters (such 
as a file specification) are enclosed within left angle ( <) and right angle (> ) 
brackets. The use of the left angle ( <) and right angle (> ) delimiters is 
noted in the format and argument descriptions of the control block macros in 
Part 11. 

At run time, you could use the following code sequence to make the file 
accessible to a Get operation: 

MOVAL OUTFAB, R6 ; Move addr into R6 

BBS #FAB$V_GET, FAB$B_FAC(R6). OK ; Branch if set 

BISB #FAB$M_GET. FAB$B_FAC(R6) ; Set if not set 

OK: ; Complete operation 

When you use VMS RMS macros, follow the coding rules used by the VAX 
MACRO assembler as described in the following list: 

• Comments must be separated from the rest of the code line by a 
semicolon (;). For example: 

$FAB BKS=4 ; Bucket size 

• All the arguments for a macro must be coded in a single statement. If the 
arguments do not fit on a line or if you want to use multiple lines, type 
the continuation character, a hyphen (-), as the last character on the line, 
and then continue typing arguments on the next line. Comments can 
follow the hyphen. For example: 

$FAB FNA=FLNAM,“ ; Filename address 

ALQ=100," ; Allocation quantity 

BKS=4 : Bucket size 

• Arguments and subarguments can be separated from each other by one 
of the following: 

— A comma, with or without spaces or tabs 
FNA=FLNAM.ALQ=100 
— A space 

FNA=FLNAM ALQ=100 
— Multiple spaces or tabs 
FNA=FLNAM ALQ=100 

The comma without a space or tab is preferred. All coding examples in 
this manual use a comma to separate arguments. 


3.2 Using the VMS RMS Macros 

This section provides examples of using the four types of VMS RMS macros. 
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3.2 Using the VMS RMS Macros 


3.2.1 Control Block Initialization Macros 

A major advantage to using the control block initialization macros is that 
they direct the initialization values to the correct field locations in the control 
block. Returned status values do not apply here because RMS evaluates this 
type of macro at assembly time. 

The program location of a control block initialization macro defines the 
beginning of the control block. Because the address of the control block is a 
required argument for most services and for some control block macros, the 
macro name should be preceded by a label, as shown in the following code 
example: 

MYFAB: $FAB 

Arguments usually require an address, such as a symbolic address, or a value. 
VMS RMS initializes the appropriate field by simply taking the supplied 
argument and placing it after the appropriate macro data declaration directive, 
as shown in the following code example: 

.ADDRESS address 
.BYTE value 

There are fields that must be treated as ASCII character strings or they 
become values in a binary options field. Such fields must be enclosed within 
left angle ( <) and right angle (> ) brackets, under the following conditions: 

• When the argument is a file specification (ASCII character string) 

• When more than one argument is supplied for a binary options field, 
where each bit option is identified by a 3-letter mnemonic 

• Where otherwise indicated in the format of the macro, such as for 
UICs and file identifiers in which multiple values separated by commas 
constitute the argument 


Here are several examples: 


MYFAB: 

$FAB 

FAC=<GET. PUT>.- 
FNM=<DEGREE^DAY.DAT>,- 

; Multioption field 
; File specification 



NXT=MYXPRO.- 
0RG=SEQ 

; XAB address 
; Single-option field 

MYXPRO: 

$XABPR0 

PRO=<RWED,RWED.R.R>,- 

UIC=<377.377> 

; File protection 
; UIC 


The complete format of each control block initialization macro is provided in 
Appendix B, showing those arguments that must be enclosed within left angle 
( <) and right angle (> ) brackets. 

Do not position the macro name in a read-only program section, because 
control block fields may receive values during the execution of a service. For 
efficiency, align the control blocks on a longword boundary. The initialization 
macros display an informational message in the listing file if the control block 
is not longword aligned. 

In summary, initialization macros must be placed in a writable data program 
section in which the data has been aligned on a longword boundary. 
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3.2 Using the VMS RMS Macros 


3.2.2 Control Block Symbol Definition Macros 

A control block symbol definition macro includes the macro name only and 
has no arguments. The macro name has the suffix "DEF" following the name 
of the initialization macro that defines all symbols in the affected control 
block. 

Control block symbol definition macros can be placed in any program section. 
VMS RMS does not provide return values for these macros. 


3.2.3 Control Block Store Macros 

A control block store macro consists of executable run-time code, so it must 
be placed within an executable code program section. RO cannot be used to 
return condition codes because these macros may use it to move arguments. 
The only detectable errors are assembly-time errors. 

The calling format of each control block store macro resembles the calling 
format of the corresponding initialization macro except that a control block 
store macro can take a run-time value as an argument. Run-time values 
include date and time values, file identifier values, device identifier values, 
directory identifier values, and record file address values. 

The following list describes other differences between the format of a control 
block store macro and its corresponding control block initialization macro: 

• The argument for the address of the FAB, NAM block, RAB, or XAB to 
receive the argument values is required. This argument can be omitted 
if the control block address is contained in RO. If this argument is not 
a register value in the form Rn, the control block address is loaded into 
RO. This argument is not present in the corresponding control block 
initialization macro. 

• For each argument that requires an address, the store macro uses the 
VAX MACRO instruction MOVAx (usually MOVAL) to move the address 
into the appropriate control block field. Thus, VAX MACRO expressions 
can be used. For instance, you can use a symbolic address to specify 
the control block address argument directly (for example, FAB=MYFAB, 
NAM=MYNAM, RAB=MYRAB, or XAB=MYXAB). 

You may also specify a register that contains the address using the form 
Rn, where n is a decimal number from 0 through 12. 

• For each argument that requires a nonkeyword data value, the store 
macro uses the VAX MACRO instruction MOVx to move data into the 
appropriate control block field. Thus, VAX MACRO expressions can be 
used. Note that a number sign (#) must precede a literal nonkeyword 
value, except when a literal value is enclosed within left angle ( <) and 
right angle (> ) brackets. However, if you specify the address where the 
argument value resides, a number sign must not precede the symbolic 
address nor the register expression that contains the address. 

• For binary option or keyword value fields, use the supplied keyword 
without a number sign and do not use a VAX MACRO expression. 
Multiple keyword arguments must be enclosed within left angle ( <) and 
right angle (> ) brackets. 
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3.2 Using the VMS RMS Macros 


In some cases, arguments are specified as run-time values using one of the 
following forms: 

• A VAX MACRO expression 

• The symbolic address of the argument value 

The format for each store macro is provided in Appendix B, which includes 
exceptions to the general rules previously described. 

Example 3-1 illustrates the use of the $XABDAT_STORE macro to set 
the creation date of the file to the beginning of a fiscal quarter, thereby 
establishing a valid starting date for the file data. 

Example 3-1 Use of the $XABDAT and $XABDAT_STORE Macros 


.TITLE GREAT - SET CREATION DATE 
; Program that uses XABDAT and XABDAT_STORE 

.PSECT LONG WRT,N0EXE 

MYFAB: $FAB ALQ=500. F0P=CBT. FAC=PUT. - 

FNM=<DISK$:[PROGRAM]SAMPLE.FILE.DAT>,- 

0RG=SEQ, RAT=CR. RFM=VAR. SHR=NIL, MRS=52, XAB=MYXDAT 


MYXDAT: $XABDAT 


ATIM: .ASCID /9-AUG-1988 00:00:00.00/ 

BTIM: .BLKQ 1 


START: 


CLOSE: 


ERROR: 


SS.ERR: 


FINI: 


.PSECT CODE N0WRT.EXE 
.ENTRY GREAT, ^M<> 

$BINTIM_S TIMBUF=ATIM. TIMADR=BTIM 
BLBC R0,SS_ERR 

$XABDAT_ST0RE XAB=MYXDAT. CDT=BTIM 
SCREATE FAB=MYFAB 
BLBC RO,ERROR 

SCLOSE FAB=MYFAB 
FINI 

FAB$L_STV+MYFAB 
FAB$L_STS+MYFAB 
#2. G^LIBSSIGNAL 
FINI 
RO 

#1, G^LIBSSIGNAL 


BRB 
PUSHL 
PUSHL 
CALLS 
BRB 
PUSHL 
CALLS 
RET 

.END GREAT 


Convert ASCII to binary time 

Branch on error 

Move time into XAB$Q_CDT 

Create file; populate 

file later 

Close file 

and exit 

Push FAB STS and 
STY on stack 
Signal error 

Push RO 
Signal error 


This short program creates a file with a creation date of midnight, 

August 9, 1988. The FAB at symbolic address MYFAB defines a sequential 
file with variable-length records up to 52 bytes in length and specifies an 
allocation size of 500 blocks using the contiguous-best-try file processing 
option. It also specifies the file specification. The .ASCID assembler directive 
defines the constant date-time character string at symbolic address ATIM. 
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3.2 Using the VMS RMS Macros 

The SYS$BINTIM system service is invoked to convert the constant ASCII 
time at symbolic address ATIM to binary format in the quadword at BTIM. 
The BTIM value is moved into the XAB$Q_CDT field of the XABDAT control 
block at symbolic address MYXDAT using the following XABDAT__STORE 
macro: 

$XABDAT_STORE XAB=MYXDAT. CDT=BTIM 

Because the creation date in field XAB$Q_CDT is input to the Create service 
($CREATE macro), the value must be stored before the program invokes th$ 
Create service. The file is created, then closed. Note that Create service errprs 
are signaled using the FAB$L«_STS and FAB$L-.STV fields, not RO. 


3.2.4 Service Macros 

The general macro format of VMS RMS service macros is described in Part f. 
Part III describes each service in detail, including the VAX calling format. 

Note that the general information applicable to invoking VMS RMS service$ 
in Chapter 2 also applies to programs written in VAX MACRO. 

The service macros use two general formats: 

1. label: macro-name 

2. label: macro-name RAB=rab-address,- 

ERR=entry,- 
SUC=entry 

The first format above takes no arguments. You supply the argument list 
within your program, and the argument pointer register (AP) is assumed to 
contain the address of the argument list. An example of this format is shown 
below. 

ARG.LOC: .BLKL 2 


MOVE 

#1.ARG_L0C 

; Move 

number of args to ARG.LOC 

MOVAL 

INFAB, ARG_L0C+4 

; Move 

FAB address to ARG_L0C+4 

MOVAL 

ARG.LOC, AP 

; Move 

ARG.LOC address to AP 

$0PEN 


: Open 

file 


In this form, the $OPEN macro expands to the following VAX MACRO cod^: 
CALLG (AP). G^SYSSOPEN 

In the second format, you supply arguments that automatically generate anj 
argument list on the stack according to the values you supplied. You specif^ 
these arguments using keywords, which can be in any order. You must 
separate keywords using a comma, a blank space, or tabs. The only argumejnt 
required when using the second format is the control block address 
(FAB=fab-address or RAB=rab-address). This argument must be either a 
general register (RO through Rll) containing the control block address, or aj 
suitable address for a PUSHAL instruction. If you omit this argument, no | 
other arguments are allowed; in other words, you must use the first format. 
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3.2 Using the VMS RMS Macros 


The ERR=entry and SUC=entry arguments are optional and, if used, provide 
the addresses of completion routine entry points. Completion routines are 
always executed as ASTs. VMS RMS places the values you supply in the 
argument list on the stack during execution of the expanded macro. These 
values must be addresses that can be used by a PUSHAL instruction. 

Here is an example of the second format: 

$0PEN FAB=INFAB 

This macro line expands to the following VAX MACRO code: 

PUSHAL INFAB 

CALLS #01. G^SYSSOPEN 

When the argument list contains a completion routine argument, an AST is 
queued. When the AST routine executes, the following conditions hold: 

• General registers RO through Rll are undefined. The AP contains the 
address of the AST argument list; the AST argument value in the AST 
argument list specifies the address of the associated control block (FAB or 
RAB). The status must be retrieved from the completion status code field 
(STS) of the associated control block. 

• Any general registers saved by an entry mask can be modified, in addition 
to RO and Rl. 

• Additional calls to VMS RMS services can be made within the completion 
routines. 

• To exit from a completion routine, you must perform any necessary 
cleanup operations and execute a RET instruction. 

The calling format of each VMS RMS service is listed alphabetically in Part III. 
The format for the Close service is shown in the following code example: 

SYSSCLOSE fab [. [err] [.sue]] 

When you use a macro to call a service, remember to omit the "SYS" prefix. 
For example, use $CLOSE instead of SYSSCLOSE. 

All file-processing macros require the FAB address as an argument and 
optionally allow you to specify the entry points for error or success condition 
handlers, as shown in the following format illustration: 

$macro FAB=fab*addr [,ERR=error-entry] [,SUC=success-entry] 

For example, to invoke the $OPEN macro and pass it the FAB address of 
INFAB and the error entry point of OPEN_ERR, you could use the following 
macro: 

$0PEN FAB=INFAB. ERR=0PEN_ERR 

Note that the $RENAME macro has a different format, as noted in Table 3-3. 
This file processing macro has the following format: 

SRENAME 0LDFAB=old-fab-addr [,ERR=error-entry] 

[,SUC=success-entry] ,NEWFAB=new-fab-addr 
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3.2 Using the VMS RMS Macros 


The format for record processing macros and block I/O macros requires the 
RAB address as an argument and optionally allows you to specify the entry 
points for error or success condition handlers, as shown in the following 
format illustration: 

$macro RAB=rab-addr [,ERR=error-entry] [,SUC=success-entry] 

Note that the $WAIT macro has a different format, in that it does not use the 
error and success arguments: 

$WAIT RAB=rab-addr 

Table 3-3 lists each service macro according to its macro type. 

Table 3—3 File, Record, and Block I/O Processing Macros 


File Record 

Processing Processing Block I/O 


$CLOSE 

SCONNECT 

SREAD 

$CREATE 

SDELETE 

SSPACE 

SDISPLAY 

SDISCONNECT 

SWRITE 

$ENTER 

SFIND 


SERASE 

SFLUSH 


SEXTEND 

SFREE 


SNXTVOL 

SGET 


$OPEN 

$PUT 


SPARSE 

SRELEASE 


SREMOVE 

SREWIND 


SRENAME' 

STRUNCATE 


SSEARCH 

SUPDATE 

SWAIT 



^Denotes macro with nonstandard format (see text). 


After calling a VMS RMS service, you should check the status code returned 
in RO (and the STS field of the appropriate control block). The recommended 
way to signal errors is to provide both the STS and STV fields of the FAB 
or RAB as arguments to the appropriate Run-Time Library routine. The 
following VAX MACRO instructions invoke the LIB$SIGNAL routine for a 
file-related (FAB) error using the CALLS (stack) form of calling a routine, 
where the FAB is located at symbolic address MYFAB (not shown): 

PUSHL MYFAB+FAB$L_STV ; Push fields on stack 

PUSHL MYFAB+FAB$L_STS ; in reverse order 

CALLS #2, G*LIB$SIGNAL ; Invoke signal routine 
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4 VMS RMS Example Programs 


This section includes very brief examples illustrating the implementation of 
VMS RMS at the VAX MACRO programming level. See the Guide to VMS 
File Applications for VMS RMS examples using the File Definition Language 
(FDL) Utility. 

Using VMS RMS macros, you can create new files, process existing files, 
extend and delete files, and read, write, update, and delete records within 
files. 

To create and process VMS RMS files, your program must contain calls to 
appropriate VMS RMS services. Generally, you make these calls by using 
the VAX RMS service macros for run-time processing. When encountered 
at run time, the expanded code of these macros generates a call to the 
corresponding VMS RMS service. Each macro and its resultant call represent 
a program request for a VMS RMS file or record service, or a block I/O 
transfer operation. 


4.1 Creating, Accessing, and Deaccessing a File 

The Create service constructs a new file according to the attributes you 
specify in the FAB for the file, whereas the Open service makes an existing 
file available for processing by your program. Both of these services, invoked 
by the $CREATE and $OPEN macros respectively, allocate resources within 
the system to establish access (a path) to a file. You must open or create a 
file to perform most file operations and any record operations on that file. 
Applications designed for shared access must declare the type of sharing at 
this time. The user specifies the various types of shared access by setting bits 
in the file access control (FAB$B_FAC) and share (FAB$B_SHR) fields in the 
appropriate FAB. 

VMS RMS provides several file-processing options for the Create service. The 
create-if option (FAB$V_CIF option in the FAB$L-_FOP field) requests that 
the file be created only if it does not exist. If the file does exist in the specified 
directory, the file is opened, not created. The Open and Create services both 
establish access to the desired file, but the Create service additionally allocates 
disk space and performs functions related to allocation. 

When you are finished processing a file, you invoke the Close service 
($CLOSE macro) to close the file, disconnect all record streams associated 
with the file and free all resources allocated to the file. If you do not explicitly 
invoke the Close service when the program image exits, VMS RMS attempts 
an implicit close. All resources associated with open files are returned when 
the files are deaccessed at image rundown time. However, process permanent 
files are not implicitly closed when an image exits. These are special files that 
the current CLI opens outside the context of a normal image. 
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4.1 Creating, Accessing, and Deaccessing a File 


4.1.1 Example of Opening and Creating Files 

Example 4-1 illustrates the use of the Open, Create, Connect, Get, Put and 
Close services to access and copy records from one file to another. Note 
that the arguments to the $FAB and $RAB macros are listed vertically on 
separate lines for ease in reading them. However, the argument list must 
be contiguous and a common programming error is omission of required 
delimiters and continuation characters when the arguments are listed in this 
manner. 

Example 4-1 Use of the Create, Open, and Close Services 


.TITLE COPYFILE 


This program copies the input file to the output file. 


.PSECT DATA.WRT.NOEXE 

INFAB: $FAB FNM = <INFILE:>.- 

Primary input file name 

DNM = <.INV> 

Default input file type 

INRAB: $RAB FAB = INFAB,- 

Pointer to FAB 

ROP = RAH,- 

Read-ahead option 

UBF = REC.BUFF,- 

Record buffer 

USZ = REC_SIZE 

and size 

OUTFAB: $FAB FNM = <0UTFILE:>,- 

Primary output file name 

DNM = <.INV>,- 

Default output file name 

FOP = CTG,- 

Make contiguous file 

FAC = <PUT>.- 

Open for PUT operations 

SHR = <NIL>,- 

Exclusive file access 

MRS = REC^SIZE,- 

Maximum record size 

RAT = CR 

Implied carriage control 

OUTRAB: $RAB FAB = OUTFAB,- 

Pointer to FAB 

ROP = WBH,- 

Write-behind option 

RBF = REC.BUFF 

Output uses same buffer 
as input 

REC.SIZE = 132 i 

; Maximum record size 

REC.BUFF: 

.BLKB REC.SIZE ; 

i Record buffer 

.PSECT CODE,NOWRT.EXE 

; Initialization - Open input and output 

files and connect streams 

.ENTRY COPYFILE,•M<R6> 

Save R6 

$0PEN FAB=INFAB 

Open input file 

BLBC R0,EXIT1 

Quit on error 

SCONNECT RAB=INRAB 

Connect to input 

BLBC R0.EXIT2 

Quit on error 

MOVL INFAB+FAB$L_ALQ,- 

Set proper size for output 

OUTFAB+FAB$L_ALQ 

SCREATE FAB=OUTFAB 

Create output file 

BLBC RO,EXITS 

Quit on error 

SCONNECT RAB=OUTRAB 

Connect to output 

BLBS RO,READ 

Branch to READ loop 

BRB EXIT4 

Trap error 


Example 4—1 Cont'd. on next page 
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4.1 Creating, Accessing, and Deaccessing a File 


Example 4-1 (Cont.) Use of the Create, Open, and Close Services 


EXITl: 

MOVAL 

INFAB,R6 

Error: Keep FAB address 


BRB 

F.ERR 

Signal file error 

EXIT2: 

MOVAL 

INRAB,R6 

Keep RAB address 


BRB 

R.ERR 

Signal record error 

EXIT3: 

MOVAL 

0UTFAB.R6 

Keep FAB address 


BRB 

F.ERR 

Signal record error 

EXIT4: 

MOVAL 

0UTRAB.R6 

If error, retain RAB addr. 


BRB 

R.ERR 

Signal record error 

; Copy records 

loop 


READ: 

$GET 

RAB=INRAB 

Get a record 


BLBS 

RO.WRITE 

Write the record 


CMPL 

R0.#RMS$.E0F 

Was error end-of-file? 


BEQL 

DONE 

Successful completion 


BRB 

EXIT2 

Error otherwise 

WRITE: 

MOVW 

INRAB+RAB$W.RSZ, - 
OUTRAB+RAB$W.RSZ 

Input RAB sets record 
size for output RAB 


$PUT 

RAB=OUTRAB 

Write the record 


BLBC 

R0.EXIT4 

Quit on error 


BRB 

READ 

Go back for more 

; Close 

files, 

signal any errors, and exit 

F.ERR: 

PUSHL 

FAB$L_STV(R6) 

: Push STV and STS of FAB 


PUSHL 

FAB$L_STS(R6) 

; on the stack 


CALLS 

BRB 

#2. G‘LIB$SIGNAL 

EXIT 

; Signal error 

R.ERR: 

PUSHL 

RAB$L_STV(R6) 

Push STV and STS of RAB 


PUSHL 

RAB$L_STS(R6) 

on the stack 


CALLS 

#2. G‘LIB$SIGNAL 

Signal error 

DONE: 

$CL0SE 

FAB=INFAB 

Close input 


$CL0SE 

FAB=OUTFAB 

and output 

EXIT: 

RET 

.END 

COPYFILE 

Return with status in RO 


This example illustrates how you can use the sequential file organization to 
create a new file by copying records from an existing file. The newly created 
file and the source file have variable-length records. 

This example assumes that an external program has identified the input file 
as a search list logical name using this statement: 

$ ASSIGN [INV]30JUN85.[INV.0LD]30JUN85 INFILE: 

This dictates that VMS RMS should look for the input file in directory [INV] 
first, and if it does not find the file, it should look in directory [INV.OLD]. 

The program also specifies the default file type INV for the input file using 
this statement: 

DNM=<.INV> ; Default input file name 

Next the program configures the RAB used for the input file (labeled INRAB). 
The first argument links the RAB to the associated FAB (INFAB) and this is 
the only required argument to a RAB. The rest of the arguments specify the 
read-ahead option (described in later text) and the record buffer for the input 
file. The Get service uses the user record buffer address (UBF) field and the 
user record buffer size (USZ) field as inputs to specify the record buffer and 
the record size, respectively. 
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Note: When you invoke the GET service, RMS takes control of the record buffer 
and may modify it. RMS returns the record size and only guarantees the 
contents from where it accessed the record to the completion of the record. 

The program then configures the FAB for the output file. The first argument 
uses the FNM field to equate the file name to the externally defined logical 
name OUTFILE. After the program specifies the default file specification 
extension for the output file, it specifies three additional FAB fields. 

First it specifies that VMS RMS should allocate contiguous space for the 
output file by setting the CTG bit in the FAB$L_FOP field of the FAB. 

Next the progam uses a program-defined variable to store the value 132 in 
the MRS field: 

MRS=REC_SIZE 
REC_SIZE= 132 

The program then specifies that each record is to be preceded by a line feed 
and followed by a carriage return whenever the record is output to a line 
printer or terminal: 

RAT=CR 

Because the program alternately reads and then writes each record, the input 
file and the output file may share the same buffer. However, because the 
Put service does not have access to the UBF and UBZ fields, the output RAB 
defines the buffer using the RBF and the RSZ fields. 

Note that the UBF, USZ, and RBF values are set prior to run time, but that 
the RSZ value is set at run time, just prior to invocation of the Put service. 
This is done because the input file contains variable-length records and the 
Put service relies on the Get service to supply each record's size by way of 
the RSZ field, an INRAB output field. 

The following statement from the sample program illustrates this feature: 

WRITE: MOVW INRAB+RAB$W_RSZ, - ; Input RAB sets record 

OUTRAB+RAB$W_RSZ ; size for output RAB 

The run-time processing macros for the input file consist of a $OPEN, a 
$CONNECT, a $GET, and a $CLOSE macro. Because the input file already 
exists, the program accesses it with a $OPEN macro. The sole argument to 
this macro identifies the FAB to the Open service: 

$0PEN FAB=INFAB 

Next, the program connects a record stream to the input file by calling the 
Connect service and specifying INRAB as the appropriate RAB: 

$C0NNECT RAB=INRAB 

Note that upon completion of each service call, the program tests the 
condition value in RO returned by the service before proceeding to the 
next call. If the call fails, the program exits with the appropriate control block 
address in R6. 

After creating the output file and establishing its record stream, the program 
begins a processing loop in which the Get service reads a record from the 
input file and the Put service writes the record to the output file. When all 
file records are copied, as indicated by the detection of the end of the file, the 
program exits to label DONE which closes both files. 


4-4 




VMS RMS Example Programs 

4.1 Creating, Accessing, and Deaccessing a File 


The Close service disconnects the record stream for all RABs connected to 
the specified FAB. In a multistream environment (more than one RAB can 
be connected to a single FAB), a program may disconnect individual record 
streams using the Disconnect service. 


4.1.2 Example of Creating a Multiple-Key Indexed File 

Example 4-2 creates an indexed file on a remote DECnet node from a 
sequential file on the local node. The indexed file contains three keys. 

Example 4-2 Use of the Create Service for an Indexed File 


.TITLE CREATEIDX - CREATE INDEXED FILE 
.IDENT /VOOl/ 

This program creates an indexed file with three keys from a 
sequential file containing a name and address list. The record 
format of the input file is shown below: 


First Name 

Column 

00-10 

Middle Initial 

Column 

11-11 

Last Name 

Column 

12-26 

Street 

Column 

27-46 

City 

Column 

47-58 

State 

Column 

59-60 

Zip Code 
Reserved for 

Column 

61-65 

new data 

Column 

66-end of record 


The input and output files are specified by the logical names SRC 
and DST, respectively. For example: 

$ DEFINE SRC DBBl:[TEST]INPUT.DAT 
$ DEFINE DST TRNTO::DRA4:[RMS.FILESlOUTPUT.DAT 
$ RUN CREATEIDX 


.SBTTL Control block and buffer storage 
.PSECT DATA NOEXE.LONG 


Define the source file FAB and RAB control blocks. 


SRC.FAB: 

$FAB FAC=<GET>,- 

F0P=<SQ0>,- 

FNM=<SRC:> 

SRC.RAB: 

$RAB FAB=SRC_FAB.- 

RAC=SEQ.- 
UBF=BUFFER,- 
USZ=BUFFER_SIZE 


; File access for GET only 
; DAP file transfer mode 

; Name of input file 

; Address of associated FAB 
; Sequential record access 
; Buffer address 
; Buffer size 


Example 4-2 Cont'd. on next page 
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4.1 Creating, Accessing, and Deaccessing a File 


Example 4—2 (Cent.) Use of the Create Service for an Indexed File 


; Define the destination file FAB and RAB control blocks. 


DST.FAB: 

$FAB FAC=<PUT>.- 

F0P=CTG.- 
FAC = <PUT>,- 
SHR = <NIL>.- 
FNM=<DST:>,- 
MRS=128.- 
RFM=VAR.- 
RAT=<CR>,- 
0RG=IDX.- 
XAB=DST_KEYO 

DST^RAB: 

$RAB FAB=DST_FAB.- 

MBF=3,- 
RAC=KEY.- 
RBF=BUFFER.- 
R0P=L0A,- 
RSZ=BUFFER_SIZE 


DST.KEYO: 

SXABKEY REF=0,- 
DAN=0,- 
DFL=1536.- 
IAN=1.- 
IFL=1536.- 
PR0L0G=3,- 
P0S=<12.0.11>,- 
SIZ=<15,1.1>,- 
NXT=DST_KEY1 

DST.KEYl: 

SXABKEY REF=1,- 
DAN=2,- 
IAN=2.- 
IFL=768,- 
P0S=47,- 
SIZ=12,- 
FLG=<CHG.DUP>.- 
NXT=DST_KEY2 

DST_KEY2: 

SXABKEY REF=2,- 
DAN=2,- 
IAN=2.- 
IFL=768,- 
P0S=59,- 
FLG=<CHG,DUP>.- 
SIZ=2.- 
NXT=DST_ALLO 


File access for PUT only 
Allocate contiguous 
Open for PUT operations 
Exclusive file access 
Name of output file 
Maximum record size 
Variable length records 
Implied carriage control 
Indexed file organization 
Address of start of XAB chain 

Address of associated FAB 
Use 3 buffers 
Random record writes 
Buffer address 
Specify initial fill size 
Buffer size 

the three keys. 

Primary key is Name 
Key reference number 
Define data XABALL 
Define data fill of 75*/, 

Define index XABALL 
Initial index fill 75*/, 

Request Prolog 3 
Segmented key: last name, 
first initial, middle initial 
Address of next XAB in chain 
1st alternate key is City 
Key reference number 
Data level (SIDR) XABALL 
Index XABALL 
Initial index fill 75*/, 
Starting key position 
Key size 

Duplicates and changes 
Address of next XAB in chain 
2nd alternate key is State 
Key reference number 
Data level (SIDR) XABALL 
Index XABALL 
Initial index fill 75*/, 
Starting key position 
Duplicates and changes 
Key size 

Designate next XAB 


; Define key definition XABs to describe 


Example 4-2 Cont'd. on next page 
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Example 4-2 (Cont.) Use of the Create Service for an Indexed File 


Define allocation control XABs to define multiple areas 


DST.ALLO; 

SXABALL AID=0,- 

ALQ=328.- 
A0P=<CBT>,- 
BKZ=4.- 
DEQ=112.- 
NXT=DST_ALL1 

DST.ALLl: 

SXABALL AID=1.- 
ALQ=8.- 
A0P=<CBT>,- 
BKZ=4.- 
DEQ=4,- 
NXT=DST_ALL2 

DST_ALL2: 

SXABALL AID=2,- 

ALQ=112,- 
A0P=<CBT>.- 
BKZ=2,- 
DEQ=38.- 
NXT=DST_ALL3 


Data area definition 
Allocation quantity and 
contiguous best try 
Bucket size of 4 blocks 
Default extension quantity 
Designate next XAB 

Primary key index area 
Allocation quantity and 
contiguous best try 
Bucket size of 4 blocks 
Default extension quantity 
Designate next XAB 

Alternate key data area 
Allocation quantity and 
contiguous best try 
Bucket size of 2 blocks 
Default extension quantity 
Designate next XAB 


; Allocate buffer to the size of the largest record being read. 

BUFFER: .BLKB 66 ; Buffer for input and output 

BUFFER_SIZE=.-BUFFER ; Buffer size 

•s|e5|t5|c5|cs|c*s|c + 3|c3|cj|e***5|e5|c5|«s|c*5|c5|c5|cs|c>|e**5|c5|c5|c**5|cHe*5|c5|c*5|esf:s|c5|c5(c5|cs|ts|e ♦♦♦♦*♦**♦♦♦*♦* *♦♦♦♦***** 


.SBTTL Mainline 

.PSECT CODE NOWRT.BYTE 

start of program 

.ENTRY CREATEIDX,^M<R6> ; Entry point 


Open the source and destination files. 



$0PEN 

FAB=SRC_FAB 

Open input file 


BLBC 

RO,EXITl 

Branch on failure 


$C0NNECT RAB=SRC_RAB 

Connect input record stream 


BLBC 

R0,EXIT2 

Branch on failure 


SCREATE 

FAB=DST_FAB 

Create output file 


BLBC 

R0.EXIT3 

Branch on failure 


$C0NNECT RAB=DST_RAB 

Connect output record stream 


BLBC 

R0.EXIT4 

Branch on failure 


BRB 

LOOP 

Bypass signaling code 

EXITl: 

MOVAL 

SRC_FAB.R6 

Keep FAB address 


BRB 

F.ERR 

Signal error 

EXIT2: 

MOVAL 

SRC_RAB,R6 

Keep RAB address 


BRB 

R.ERR 

Signal error 

EXIT3: 

MOVAL 

DST_FAB.R6 

Keep FAB address 


BRB 

F.ERR 

Signal error 

EXIT4: 

MOVAL 

DST_RAB.R6 

Keep RAB address 


BRB 

R.ERR 

Signal error 

Example 4-2 Cont'd. on next page 
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Example 4—2 (Cent.) Use of the Create Service for an Indexed File 


Transfer records until end-of-file is reached. 


LOOP: 

$GET 

RAB=SRC_RAB 

Read next rec from input file 


BLBS 

RO.PUT 

Branch on success 


CMPL 

R0.#RMS$_E0F 

Was it end-of-file (EOF)? 


BNEQ 

EXIT2 

Branch if not EOF error 


BRB 

CLOSE 

Close and exit if EOF 

PUT: 

$PUT 

RAB=DST_RAB 

Write 66-byte record to output 


BLBS 

RO.LOOP 

On success, continue loop 


BRB 

EXIT4 

On error, signal and exit 

; Close 

the source and destination files 


F.ERR: 

PUSHL 

FAB$L_STV(R6) 

Push STV and STS fields 


PUSHL 

FAB$L_STS(R6) 

on stack 


CALLS 

#2, G'LIBSSIGNAL 

Signal file error 


BRB 

EXIT 

Exit 

R.ERR: 

PUSHL 

RAB$L_STV(R6) 

Push STV and STS fields 


PUSHL 

RAB$L_STS(R6) 

on stack 


CALLS 

#2, G‘LIB$SIGNAL 

Signal file error 

CLOSE: 

$CL0SE 

FAB=DST_FAB 

Close output file 


SCLOSE 

FAB=SRC_FAB 

Close input file 

EXIT: 

$EXIT_S 


Exit 


.END 

CREATEIDX 

Specify starting address 


This example program creates an indexed file with a primary key and two 
alternate keys that are defined by appropriate key definition control blocks 
(XABKEY). For efficiency, the file is divided into areas consisting of a data 
area and an index area for each key using multiple allocation control blocks 
(XABALL). 


In each XABKEY, the DAN and IAN arguments (XAB$B_DAN and XAB$B_ 
IAN fields) indicate the area identification number (AID) of the corresponding 
XABALL. By setting the RAB$V_LOA bit in RAB field RAB$L_ROP, the 
program indicates that VMS RMS should use the DFL and IFL arguments 
(XAB$W_DFL and XAB$W_IFL fields) to determine the maximum initial fill 
size (in bytes) for data and index buckets (each bucket contains the number of 
blocks specified in the XABALL BKZ argument, XAB$B_BKZ field). 


These are the XABKEY and XABALL 
NAME key) in this example: 

DST.KEYO: 

SXABKEY REF=0.- 
DAN=0,- 
DFL=1536.- 
IAN=1,- 
IFL=1536.- 
PR0L0G=3.- 


control blocks for the primary key (the 

; Primary key is Name 
; Key reference number 
; Define data XABALL 
; Define data fill of 75% 

; Define index XABALL 
; Initial index fill 75% 

; Request Prolog 3 
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DST.ALLO: 

SXABALL AID=0,- 

ALQ=328.- 
A0P=<CBT>,- 
‘ BKZ=4.- 
DEQ=112,- 
NXT=DST_ALL1 

DST.ALLl: 

$XABALL AID=1.- 
ALQ=8.- 
A0P=<CBT>.- 
BKZ=4.- 
DEQ=4,- 
NXT=DST_ALL2 


Data area definition 
Allocation quantity and 
contiguous best try 
Bucket size of 4 blocks 
Default extension quantity 
Designate next XAB 

Primary key index area 
Allocation quantity and 
contiguous best try 
Bucket size of 4 blocks 
Default extension quantity 
Designate next XAB 


The allocation information was obtained using the File Definition Language 
(FDL) editor which is especially useful when you are creating large indexed 
files. The DCL commands CREATE/FDL and CONVERT can be used to 
create files by using an FDL file produced by the FDL editor, without any 
programming. Instead of using the multiple XABs for the key definition and 
area allocations in this program, a simpler approach is to use the FDL file 
produced by the FDL editor by invoking the FDL routines FDL$PARSE and 
FDL$RELEASE (for more information on these routines, see the VMS Utility 
Routines Manual). 


Fixed-length records are copied from the sequential input file on the local 
node to the indexed file on the remote node. Each variable-length output 
record is initially 66 bytes long and may be extended to a maximum of 128 
bytes. A subsequent example in this document shows how to access this file 
using different key paths. 


4.2 Processing File Specifications 

The file name and file specification services. Parse and Search, are used for 
relatively complex operations such as processing wildcard characters. 

Before you can perform operations on a file, you must establish a path to 
the file. You do this by specifying the file specification string address and 
size (FAB$L_FNA and FAB$B_FNS) fields (and possibly the default file 
specification string address and size fields) of the FAB to describe an ASCII 
string within the program. In this ASCII string, you can have a concatenation 
of the network node name; a logical or device name; the directory name; and 
the file name, type, and version number. 

If a logical name is used, VMS RMS translates the logical name into 
its equivalent file specification before it applies defaults to any missing 
components of the file specification. If the logical name is a search list 
logical name, VMS RMS translates each element of the search list into an 
equivalent file specification before it applies defaults to that element. When 
using the Search service, a file specification that may contain a search list 
logical name must be handled as if wildcard characters were present in the 
file specification. 

The Parse service is required prior to the Search service in order to examine 
the file specification for wildcard characters or a search list. If the file is 
found, the Parse service sets a NAM block bit that VMS RMS uses internally 
and sets an appropriate value in the wildcard character context which is used 
as input by the Search service. The Parse service is invoked once, then the 
Search service is repetitively invoked as many times as there are files that 
match the original file specification. 
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If a wildcard is present, the Search service attempts to find all files that match 
the file specification. If an asterisk (*) is in the directory field, all directories 
on the specified device are searched for files that match the remaining file 
specification components. As with the use of wildcard characters, when a 
search list logical name is present, a single Parse service and multiple Search 
services return all files that match the file specification. With search lists, 
however, all list elements are searched for matching file specifications in 
the specified order without regard to uniqueness between the resulting file 
specifications. Search lists can be used in place of (or in addition to) wildcard 
characters to specify a more efficient search order, which can mean different 
combinations for the device, directory, file name, file type, and version 
number parts of a file specification. Search lists can also contain wildcard 
characters, if needed. 

In summary, the Parse and Search services use a search list logical name very 
much like a wildcard. Unlike the case of opening a file, in which the first 
instance where the file is found successfully ends the use of additional search 
list file specifications, the Parse and Search services use all search list file 
specifications. 

Example 4-3 shows how the SPARSE and SSEARCH macros can be used in 
wildcard processing. 

Example 4-3 Wildcard Processing Using Parse and Search Services 


.TITLE WILD 


Program to accept wildcard characters in input (partial) file 
specification and display full file specification. 


$NAMDEF 


; NAM block definitions 

.PSECT 

DATA.NOEXE.WRT 


NAM.BLK: 

$NAM 

RSA=RES_STR,- 

; Result buffer address 


RSS=NAM$C_MAXRSS.- 

; Result buffer size 


ESA=EXP_STR.- 

; Expanded buffer address 


ESS=NAM$C_MAXRSS 

: Expanded buffer size 

FAB^BLK: 

$FAB 

F0P=NAM.- 

; Use NAM block option 


NAM=NAM_BLK.- 

; Pointer to NAM block 


FNA=INP_STR 

; Addr of file name string 

EXP.STR: 


; Expanded string buffer 

.BLKB 

NAM$C_MAXRSS 


RES.STR: 


; Resultant string buffer 

.BLKB 

NAMSC.MAXRSS 

RES^STR.D: 


; Resultant string descriptor 

.BLKL 

1 


.LONG 

RES.STR 


INP^STR: 


: Input string buffer 

.BLKB 

NAM$C_MAXRSS 


INP_STR_D: 


; Input string descriptor 

.LONG 

NAM$C_MAXRSS 


.LONG 

INP.STR 


INP_STR_LEN: 


; Input string length 

.BLKL 

1 


Example 4—3 Cont'd. on next page 
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Example 4-3 (Cent.) 


Wildcard Processing Using Parse and Search 
Services 


PROMPT.D: 


.ASCID 

.PSECT 
.ENTRY 
PUSHAB 
PUSHAB 
PUSHAB 


; User prompt string 
/Please enter the file specification: / 


CODE.EXE,NOWRT 

WILD.^Mo 

INP_STR_LEN 

PROMPT.D 

INP.STR.D 


Address for string length 
Prompt string descriptor 
String buffer descriptor 


CALLS #3,G‘LIB$GET_INPUT 

; Get input string value 

BLBC RO.EXIT 

; Quit on error 

Store user input string and perform initial parse to 
set up VMS RMS context for subsequent search. 

MOVB INP.STR.LEN, - 

: Set string size 

FAB_BLK+FAB$B_FNS 


SPARSE FAB=FAB_BLK 

; Parse the file spec 

BLBC RO,F.ERR 

; Quit and signal on error 


Search until all possibilities are exhausted. 


SEARCH.LOOP: 



SSEARCH FAB=FAB_BLK ; 

Find next file 


BLBC 

RO.SRCHERR ; 

Any more? 

; Print 

out the 

resultant string from the search operation 


MOVZBL 

NAM_BLK+NAM$B_RSL, - 
RES_STR_D 

Set string length 


PUSHAB 

RES.STR.D 

String descriptor 


CALLS 

#1,G*LIB$PUT.0UTPUT 

Output the result 


BLBC 

RO.EXIT 

Quit on error 


BRB 

SEARCH.LOOP 

Go for more 

SRCHERR 



If the error is "No more 


CMPL 

RO,#RMS$_NMF 

files" then this is the 


BEQL 

S.EXIT 

normal completion of the 
search loop. 

F.ERR: 

PUSHL 

FAB.BLK+FABSL.STV 

Push STV and STS on stack 


PUSHL 

FAB.BLK+FABSL.STS 

in reverse order 


CALLS 

#2. G*LIB$SIGNAL 

Signal error 

S.EXIT: 

EXIT: 

MOVL 

RET 

#1,R0 

Suppress "No More Files" 


.END WILD 



This program is designed to locate all files corresponding to a partial file 
specification input. The program prompts the user for an input string, which 
can consist of a partial file specification, using the wildcard characters 
and/or any type of logical name, including a search list logical name. In 
many respects, this program emulates the DCL command DIRECTORY, 
which is discussed in the VMS DCL Dictionary. 

The program illustrates the use of the SPARSE and SSEARCH file name 
processing macros. Here is the program statement that invokes the Parse 
service for parsing the file name string: 


SPARSE FAB=FAB_BLK 
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Before invoking the Parse service (SPARSE macro), the program moves the 
input string length to the file name string (FAB$B_FNS) field. If the Parse 
service returns an error completion status, the program branches to the 
F_ERR error routine. 

Assuming no error, the program searches the disk directories specified by the 
expanded string area address field in the NAM block (NAM$L_ESA) until all 
possible files conforming to the partial file specification input are found. Here 
is the program line that invokes the Search service: 

$SEARCH FAB=FAB_BLK 

A status test is performed immediately after the $SEARCH macro. If an 
error is detected, the program branches to the SRCHERR label. If a no-more- 
files condition is detected, VMS RMS returns the RMS$_NMF message to 
indicate that all files that match the specification have been found. (This 
error, however, is not signaled.) 

This program contains two Run-Time Library routines: LIB$GET_INPUT and 
LIB$PUT_OUTPUT. The LIB$GET_INPUT routine inputs a record from the 
current controlling input device, specified by SYS$INPUT, using the VMS 
RMS Get service. The LIB$PUT_OUTPUT routine outputs a record (line) to 
the current controlling output device, specified by SYS$OUTPUT, using the 
VMS RMS Put service. Both routines are discussed in greater detail in the 
VMS Run-Time Library Routines Volume. 


4.3 Connecting and Disconnecting Record Streams 

To associate or disassociate a file with one or more record streams, VMS RMS 
provides the Connect and Disconnect services, which are invoked using the 
$CONNECT and $DISCONNECT macros. 

Before reading and writing file records, the program must open (or create) 
the input and output files and then connect the files to the appropriate record 
streams by executing the $OPEN (or $CREATE) macro followed by the 
$CONNECT macro. 

Closing a file implicitly disconnects the record stream. Use the Disconnect 
service to explicitly disconnect a record stream that is not to be used 
immediately. This keeps the file open but releases various data structures 
for use by other processes until your program needs the record stream. 

Example 4-4 shows a program in which a user-entered reply determines 
which key path is selected to access the indexed file created in Example 4-2. 
The user-entered value determines the value specified for the RAB$B_KRF 
field. The RAB$B_H..RF value is set before the connect operation occurs 
because this field is input to the Connect service. 
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Example 4-4 Use of the Connect Service and Multiple Keys 


.TITLE MULTIKEY 


REC_SIZE=128 

.PSECT 


DATA NOEXE.LONG 


** RMS DATA 


MODFAB: 

$FAB 

FNM=<DATA_OUTPUT.DAT>.- 


FAB file spec. 




FAC=<GET>.- 


Get access needed 




SHR=<GET. UPD, PUT>.- 


Allow Get, Update, Put 




MRS=REC_SIZE 


Specify record size 


MODRAB: 

$RAB 

FAB=MODFAB,- 


RAB; indicate FAB 




MBF=3,- 


Use 3 buffers 




UBF=REC_MODBUF,- 


Specify buffer 




USZ=REC_SIZE.- 






KRF=0 


; Primary is default key 


REC.START: 

.LONG REC.SIZE 


; Record buffer 




.ADDRESS REC.MODBUF 




REC MODBUF: 

.BLKB REC.SIZE 







TERMINAL I/O DATA *♦ 


MPROO: 

.ASCID 

/ / 




MPROl: 

.ASCID 

/Enter list order: 1-by name, 2-by city, 3-by state, 9-end :/ 


ENTRYERR: 

.ASCID /* ♦ Value entered must 

be 1. 2. 3, or 9. * ♦/ 


REGANS: 


.LONG 1 






.ADDRESS REGBUF 




REGBUF: 


.BLKB 1 




DONE: 

.ASCID 

/Press RETURN to continue/ 



’ 

.PSECT 

CODE 




START: 

.WORD 

^M<> 




INPUT: 

PUSHAL 

MPROO ; 

Get input 



PUSHAL 

MPROl ; 

Display prompt 



PUSHAL 

REGANS 





CALLS 

#3, GUIB$GET_INPUT 





BLBC 

RO,FINI 





CMPB 

#^A/1/,REGBUF 

Test 

value of menu answer 



BEQLU 

PRIM 

1 means primary 



CMPB 

#-* A/2/, REGBUF 

Continue testing 



BEQLU 

ALTl 

2 means first alternate 



CMPB 

#^A/3/,REGBUF 

Continue testing 



BEQLU 

ALT2 

3 means second alternate 



CMPB 

A/9/,REGBUF 

Continue testing 



BEQLU 

FINI 

9 means end program 


BADANS: 

PUSHAL 

ENTRYERR 

otherwise, display error message 



CALLS 

#1, GUIB$PUT_OUTPUT 





BLBC 

R0,FINI 





BRB 

INPUT 

; Entry 

error; retry 


PRIM: 

MOVB 

#0,MODRAB+RAB$B_KRF 

; Set key of reference in RAB 



BRB 

OPEN 




ALTl: 

MOVB 

#1,MODRAB+RAB$B_KRF 

; Set key of reference in RAB 



BRB 

OPEN 




ALT2: 

MOVB 

#2,MODRAB+RAB$B_KRF 

; Set key of reference in RAB 


OPEN: 

$0PEN 

FAB=MODFAB 

; Open file 



BLBC 

RO,ERROR_OPEN 





$C0NNECT RAB=MODRAB 

; Connect record stream 



BLBC 

RO,ERROR 




Example 4-4 Cont'd. on next page 
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Example 4-4 (Cont.) Use of the Connect Service and Multiple Keys 


NEXT: 

$GET 

RAB=MODRAB 

; Get record 


CMPL 

#RMS$_E0F.RO 

; Test if EOF 


BEQLU 

CLEAN 



BLBC 

RO,ERROR 



MOVZWL 

RAB$W_USZ+MODRAB,REC. 

.START ; Set ASCII descriptor length 


PUSHAL 

REC.START 

: Display each record 


CALLS 

#1, G-LIB$PUT_OUTPUT 



BLBS 

RO.NEXT 



BRB 

FINI 

; Repeat until EOF 

CLEAN 

SCLOSE 

FAB=MODFAB 

; Close file 


BLBC 

R0,ERR0R_0PEN 



PUSHAL 

MPROO 



CALLS 

#1. G''LIB$PUT_OUTPUT 



BLBC 

RO.FINI 



PUSHAL 

DONE 



PUSHAL 

REGANS 



CALLS 

#2, GUIB$GET_INPUT 



BLBC 

RO.FINI 



BRB 

INPUT 


ERROR. 

.OPEN: 




PUSHL 

MODFAB+FAB$L_STV 

; Error opening 


PUSHL 

MODFAB+FAB$L_STS 

; file. Signal error 


CALLS 

#2, GUIBSSIGNAL 

: using LIBSSIGNAL. 


BRB 

FINI 

; End program 

ERROR: 

PUSHL 

MODRAB+RAB$L_STV 

; Record-related error 


PUSHL 

MODRAB+RAB$L_STS 



CALLS 

#2, GUIBSSIGNAL 

; Signal error, then 


$CL0SE 

FAB=MODFAB 

; close file 

FINI: 

RET 




.END 

START 



Here the SHR argument limits access to processes that perform the Get 
service. Put service, and Update service. If you anticipate no file modifications 
as your program accesses the file, you can improve performance by having the 
SHR argument limit access to processes that use the Get service (SHR=GET). 

Errors are signaled according to the recommended practice of using the 
FAB$L_STS and FAB$L_STV fields for file errors and RAB$L_STS and 
RAB$L_STV fields for record errors. 


4.4 Other File-Processing Operations 

Other VMS RMS file services include the Display, Erase, Extend, Remove, 
and Rename services, which can be invoked using the $DISPLAY, $ERASE, 
$EXTEND, SREMOVE, and $RENAME macros, respectively. 

Example 4-5 illustrates the use of the Rename service to rename a file from 
directory [USER] named NAMES.DAT to directory [USER.HISTORYl named 
OLD_NAMES.DAT. 
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Example 4—5 Use of the Rename Service 


.TITLE RENAME 

Program that renames a file into a different directory and 
displays the resultant string. 

.PSECT DATA.NOEXE.WRT 

Define old FAB, old NAM, new FAB, new NAM, and buffers 


OLD.FAB; ; Define old file FAB 


$FAB 

FNM=<[USER]NAMES.DAT>.- 




NAM=OLD_NAM 

Pointer to NAM block 


OLD.NAM: 


Define old file NAM 


$NAM 

ESA=EXP_OLD.- 

Equivalence string 



ESS=NAM$C_MAXRSS.- 

address and size 



RSA=RES_OLD,- 

Resultant string 



RSS=NAM$C_MAXRSS 

address and size 


NEW FAB: 


Define new file FAB 


$FAB 

FNM=<[USER.HISTORY]OLD.NAMES.DAT>.- 



NAM=NEW_NAM ; 

; Pointer to NAM block 


NEW_NAM: 




$NAM 

ESA=EXP_NEW,- 

Equivalence string 



ESS=NAM$C_MAXRSS,- 

address and size 



RSA=RES_NEW,- 

Resultant string 



RSS=NAM$C_MAXRSS 

address and size 


EXP.OLD: 


Old file equivalence 


.BLKB 

NAM$C_MAXRSS 

string buffer 


EXP_NEW: 


New file equivalence 


.BLKB 

NAM$C_MAXRSS 

string buffer 


RES.OLD: 


Old file resultant 


.BLKB 

NAM$C_MAXRSS 

string buffer 


RES_0LD_D: 


String descriptor 


.BLKL 

1 



.LONG 

RES.OLD 



RES.NEW: 


; New file resultant 


.BLKB 

NAMSC.MAXRSS 

; string buffer 


RES.NEW.D: 


; String descriptor 


.BLKL 

1 



.LONG 

RES.NEW 



MESS: .ASCID 

/has been successfully relocated to / 


.PSECT 

C0DE,EXE,N0WRT 



.ENTRY 

RENAME,^M<> 





; Rename file 


SRENAME 0LDFAB=0LD_FAB. NEWFAB=NEW_FAB 


BLBC 

RO,ERROR 





; Set up descriptors 


Example 4—5 Cont'd. on next page 
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Example 4—5 (Cont.) Use of the Rename Service 



MOVZBL 

OLD.NAM+NAM$B_RSL.RES.OLD.D 


MOVZBL 

NEW_NAM+NAM$B.RSL,RES_NEW_D 


PUSHAL 

RES.OLD.D 

Push resultant name, 


CALLS 

#1,G^LIB$PUT.OUTPUT 

display old file spec. 


BLBC 

RO.TERM.ERROR 

Branch on error 


PUSHAL 

MESS 

Push message on stack, 


CALLS 

#l.GaiB$PUT.OUTPUT 

display message 


BLBC 

RO.TERM.ERROR 

Branch on error 


PUSHAL 

RES.NEW.D 

Push resultant name, 


CALLS 

#1,G^LIB$PUT.0UTPUT 

display new file spec. 


BLBS 

RO.DONE 

Branch on success 

TERM. 

ERROR: 




PUSHL 

RO ; 

Signal output error 


CALLS 

#1.G^LIB$SIGNAL ; 

from RO 


BRB 

DONE 


ERROR 

: PUSHL 

OLD.FAB+FABSL.STV ; 

Push STV and STS on 


PUSHL 

OLD.FAB+FABSL.STS ; 

stack (reverse order) 


CALLS 

#2,GUIB$SIGNAL ; 

Signal error 

DONE: 

RET 



.END RENAME 



This program uses the Rename service to change both the directory and the 
name of the object file, which is being replaced by a new file (created by a 
separate program). If the Rename service executes correctly, the resultant 
file specification of the old file, the message defined by the ASCII descriptor 
following the label MESS, and the resultant file specification of the new file 
are displayed as verification that the Rename service successfully completed. 

4.5 Retrieving and Inserting Records 

The record-processing services provided by VMS RMS insert records into a 
file and retrieve records from a file. These services are the Find, Get, and 
Put services, which can be invoked by the $FIND, $GET, and $PUT macros, 
respectively. 

Example 4—6 illustrates the use of the $GET and $PUT macros. It connects 
the input and output record streams, reads a record from an indexed file, and 
writes the record to a relative file. The program illustrates the use of the key 
string buffer, the key string descriptor and the key string length when reading 
indexed records and it includes the use of a user prompt string. 
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Example 4—6 Use of the Get and Put Services 


.TITLE LOOKUP 

; This program looks up records in the input file and 


; writes the records to the output file. 


.PSECT 

DATA.WRT.NOEXE 


INFAB: $FAB 

FNM = <INFILE:>,- 

Input file logical name 


SHR = <GET.PUT.UPD,DEL> 

Allow read/write sharing 

INRAB: $RAB 

FAB = INFAB.- 

Pointer to FAB 


KBF = INP.STR,- 

Key buffer 


KRF = 0.- 

Primary key 


RAC = KEY,- 

Keyed access 


ROP = WAT,- 

Wait for record 


UBF = REC.BUFF,- 

Record buffer 


USZ = REC.SIZE 

and size 

OUTFAB: $FAB 

FNM = <OUTFILE:>,- 

Output file logical name 


BKS ^ 3.- 

3 blocks per bucket 


MRS = REC.SIZE,- 

Maximum record size 


ORG = REL,- 

Relative file 


RAT = CR 

Implied carriage control 

OUTRAB: $RAB 

FAB = OUTFAB,- 

Pointer to FAB 


RBF = REC.BUFF 

Output uses same buffer 



as input 

REC.SIZE = 132 


Maximum size records 

REC.BUFF: 



.BLKB 

REC.SIZE : 

, Record buffer 

INP.STR: 


; Key string buffer 

.BLKB 

REC.SIZE 


INP.STR.D: 


; Key string descriptor 

.LONG 

REC.SIZE 


.LONG 

INP.STR 


INP_STR_LEN: 


; Key string length 

.BLKL 

1 


PROMPT.D: 


; User prompt string 

.ASCID 

/Please input key value: 

/ 

.PSECT 

CODE.NOWRT.EXE 


; Initialization - Open input and output 

files and connect streams 

.ENTRY 

LOOKUP,"M<> 

No registers to save 

$0PEN 

FAB=INFAB 

Open input file 

BLBC 

RO.EXITl 

Quit on error 

SCONNECT RAB=INRAB 

Connect to input 

BLBC 

R0.EXIT2 

Quit on error 

$CREATE FAB=OUTFAB 

Create output file 

BLBC 

RO.EXITS 

Quit on error 

SCONNECT RAB=OUTRAB 

Connect to output 

BLBC 

R0.EXIT4 

Quit on error 

BRB 

READ 

Skip error branching 

EXITl: MOVAL 

INFAB, R6 

Keep INFAB address 

BRW 

F.ERR 

Signal FAB error 

EXIT2: MOVAL 

INRAB. R6 

Keep INRAB address 

BRW 

R.ERR 

Signal RAB error 

EXIT3: MOVAL 

OUTFAB, R6 

Keep OUTFAB address 

BRB 

F.ERR 

Signal FAB error 

EXIT4: MOVAL 

OUTRAB, R6 

Keep OUTRAB address 

BRB 

R.ERR 

Signal RAB error 

Example 4—6 Cont'd. on next page 
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Example 4—6 (Cont.) Use of the Get and Put Services 


; Loop to copy 

records 


READ: 

PUSHAB 

INP.STR.LEN 

Address for string length 


PUSHAB 

PROMPT.D 

Prompt string descriptor 


PUSHAB 

INP.STR.D 

String buffer descriptor 


CALLS 

#3.G*LIB$GET.INPUT 

Get input string value 


BLBS 

RO.GET 

Quit on error or end-of-file 


CMPL 

R0.#RMS$_E0F 

Was error end-of-file? 


BEQL 

DONE 

Successful completion 


BRB 

EXIT 

Error otherwise 

GET: 

MOVB 

INP.STR.LEN. - 

Set key size 


$GET 

INRAB+RAB$B.KSZ 

RAB=INRAB 

Get a record 


BLBS 

RO.PUT 

Put if successful 


CMPL 

R0.#RMS$.RNF 

No such record? 


BEQL 

READ 

Try again 


BRB 

EXIT2 

Error otherwise 

PUT: 

MOVW 

INRAB+RAB$W.RSZ. - 

Set the record size 


$PUT 

OUTRAB+RAB$W.RSZ 

RAB=OUTRAB 

for output 

Write the record 


BLBC 

R0,EXIT4 

Quit on error 


BRB 

READ 

Go back for more 

; Close 

files and exit 


F_ERR: 

PUSHL 

FAB$L_STV(R6) ; 

Push STV and STS on 


PUSHL 

FAB$L_STS(R6) ; 

stack in reverse order 


CALLS 

#2. G‘LIB$SIGNAL ; 

Signal message 

R_ERR: 

BRB 

PUSHL 

EXIT 

RAB$L_STV(R6) 

Push STV and STS on 


PUSHL 

RAB$L_STS(R6) 

stack in reverse order 


CALLS 

#2. G'LIBSSIGNAL 

Signal message 

DONE: 

SCLOSE 

FAB=INFAB 

Close input 


$CL0SE 

FAB=OUTFAB 

and output 

EXIT: 

RET 


Return with status in RO 


.END 

LOOKUP 



This program writes records from an existing indexed input file into a newly 
created relative output file. 

The program configures the file-sharing field (FAB$B_SHR) in the input FAB 
to permit sharing of the file by processes that use the Get, Put, Update and 
Delete services. 

The output FAB sets the bucket size field (FAB$B_BKS) at three blocks per 
bucket, limits the record size in the output file to 132 bytes, specifies the 
relative file organization and specifies an implicit carriage control when the 
file output is directed to a terminal. 

The RAB for the input file establishes the key data, sets the WAIT record 
option and defines the record buffer. The output RAB locates the record 
buffer. The rest of the first program section assigns values and allocates space 
to various program variables. After the program opens and creates the two 
files and connects the record streams, it executes a series of instructions at 
label READ that input the required key values and the user prompt. Then the 
program uses the $GET and $PUT macros to invoke the respective services 
for retrieving and inserting the records. The $GET macro uses the INRAB, 
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and the $PUT macro uses the OUTRAB as shown in the following program 
statements: 

$GET RAB=INRAB 

$PUT RAB=OUTRAB 

Each time the program reads or writes a record, it performs a status check. If 
the status check is successful, the program branches back to the READ label 
for the next record. If any of the status checks indicate an error, the program 
branches to the appropriate error handler before exiting. 

When the program completes the records transfers, it branches to the DONE 
label to close the record and exit. 


4.6 Deleting Records 


This service can only be used with relative and indexed files. Example 4-7 
illustrates use of the Delete service. 

Example 4—7 Use of the Delete Service 

.TITLE DELETE 


; This program looks up records in the input file and 

; deletes those records. 


.PSECT DATA.WRT.NOEXE 


INFAB: $FAB FNM = <INFILE:>.- 

Input file logical name 

FAC = <DEL,GET> 

DEL access 

INRAB: $RAB FAB = INFAB.- 

Pointer to FAB 

KBF = INP_STR,- 

Key buffer 

KRF = 0.- 

Primary key 

RAC = KEY 

Keyed access 

REC.SIZE = 132 

Maximum size records 

INP.STR: 

Key string/record buffer 

.BLKB REC.SIZE 


INP.STR.D: ; 

i Key string descriptor 

.LONG REC.SIZE 


.LONG INP.STR 


INP.STR.LEN: i 

: Key string length 

.BLKL 1 


KEY.PMT.D: 

; Key value prompt string 

.ASCID /Please enter key value: 

/ 

.PSECT C0DE.N0WRT.EXE 


; Initialization - Open file and connect 

stream 

.ENTRY DELETE,^M<> 

No registers to save 

$0PEN FAB=INFAB 

Open input file 

BLBC RO.F.ERR 

Quit on error 

SCONNECT RAB=INRAB 

Connect to input 

BLBC RO.R.ERR 

Quit on error 

Example 4-7 Cont'd. on next page 
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Example 4-7 (Cent.) Use of the Delete Service 


; Delete record loop 


READ: 



PUSHAB 

INP.STR.LEN 


PUSHAB 

KEY.PMT.D 


PUSHAB 

INP_STR_D 


CALLS 

#3.GUIB$GET_INPUT 


BLBS 

RO.FIND 


CMPL 

RO.#RMS$_EOF 


BEQL 

DONE 


BRB 

EXIT 

FIND: 

MOVB 

INP_STR_LEN. - 



INRAB+RAB$B_KSZ 


$FIND 

RAB=INRAB 


BLBS 

RO.DEL 


CMPL 

RO,#RMS$_RNF 


BEQL 

READ 


BRB 

R_ERR 

DEL: 

$DELETE RAB=INRAB 


BLBC 

RO.R.ERR 


BRB 

READ 

; Close 

files and exit 

F.ERR: 

PUSHL 

FAB$L_STV+INFAB 


PUSHL 

FAB$L_STS+INFAB 


CALLS 

#2, G*LIB$SIGNAL 


BRB 

EXIT 

R.ERR: 

PUSHL 

RAB$L_STV+INRAB 


PUSHL 

RAB$L_STS+INRAB 


CALLS 

#2. G*LIB$SIGNAL 

DONE: 

$CLOSE 

FAB=INFAB 

EXIT: 

RET 



.END 

DELETE 


Address for string length 
Prompt string descriptor 
String buffer descriptor 
Get input string value 
Quit on error or end-of-file 
Was error end-of-file? 
Successful completion 
Error otherwise 
Set key size 

Locate the record 
Continue if found 
No such record? 

Try again 
Error otherwise 
Delete the record 
Quit on error 
Go back for more 


Push STV and STS on 
stack in reverse order 
Signal message 

Push STV and STS on 
stack in reverse order 
Signal message 
Close files 

Return with status in RO 


This program uses a key to find and delete a record. To use the $DELETE 
macro, the $FAB macro for the file must set the FAB$V_DEL bit as shown in 
the following code example: 

INFAB: $FAB FNM=<INFILE:>.- 

FAC=<DEL> 

The following program statement invokes the Delete Service and points to 
the input RAB: 

SDELETE RAB=INRAB 


# 
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4.7 Updating Records 

Example 4-8 illustrates the use of the Update service. 

Example 4-8 Use of the Update Service 


.TITLE UPDATE 

; This program looks up records in the input file and 
; updates those records. 


.PSECT 

DATA.WRT.NOEXE 


INFAB; $FAB 

FNM = <INFILE:>.- 

Input file logical name 


FAC = <GET.UPD> 

Read and Write access 

INRAB: $RAB 

FAB = INFAB.- 

Pointer to FAB 


KBF = INP.STR,- 

Key buffer 


KRF = 0.- 

Primary key 


RAC = KEY,- 

Keyed access 


RBF = INP.STR 

Record buffer 

REC_SIZE = 132 


Maximum size records 

INP.STR: 


Key string/record buffer 

.BLKB 

REC.SIZE 


INP_STR_D: 


Key string descriptor 

.LONG 

REC.SIZE 


.LONG 

INP.STR 


INP_STR_LEN: 


Key string length 

.BLKL 

1 


KEY.PMT.D: 


Key value prompt string 

.ASCID 

/Please input key value: 

/ 

DATA.PMT.D: 


i Data value prompt string 

.ASCID 

/Please input new record 

value: / 

.PSECT 

CODE,NOWRT,EXE 


; Initialization - Open file and connect 

stream 

.ENTRY 

UPDATE."M<> 

No registers to save 

$0PEN 

FAB=INFAB 

Open input file 

BLBC 

RO.FAB.E 

Quit on error 

$C0NNECT RAB=INRAB 

Connect to input 

BLBC 

RO.RAB.E 

Quit on error 

BRB 

READ 

Begin update loop 

FAB.E: BRW 

F.ERR 

File (FAB) error 

RAB.E: BRW 

R.ERR 

Record (RAB) error 

: Update record 

loop 


READ: 

; Prompt for key value to look up. 


PUSHAB 

INP.STR.LEN 

; Address for string length 

PUSHAB 

KEY.PMT.D 

; Prompt string descriptor 

PUSHAB 

INP.STR.D 

; String buffer descriptor 

CALLS 

#3.GUIB$GET.INPUT 

; Get input string value 

BLBS 

RO.FIND 

; Quit on error or end-of-file 

CMPL 

R0.#RMS$.E0F 

; Was error end-of-file? 

BEQL 

ALL.D 

: Successful completion 

BRW 

EXIT 

; Error otherwise 

Example 4—8 Cont'd. on next page 
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Example 4—8 (Cont.) Use of the Update Service 


ALL.D: 

BRW 

DONE 


FIND: 

MOVE 

INP.STR.LEN, - 
INRAB+RAB$B_KSZ 

; Set key size 


$FIND 

RAB=INRAB 

Locate the record 


BLBS 

RO.UPD 

Continue if found 


CMPL 

R0,#RMS$_RNF 

No such record? 


BEQL 

READ 

Try again 


BRB 

R.ERR 

Error otherwise 

; Prompt for new data record. 


UPD; 


PUSHAB 

INP.STR.LEN 

Address for string length 


PUSHAB 

DATA_PMT_D 

Prompt string descriptor 


PUSHAB 

INP.STR.D 

String buffer descriptor 


CALLS 

#3.GUIB$GET_INPUT 

Get input string value 


BLBC 

RO.EXIT 

Quit on error 


MOVW 

INP_STR_LEN. - 
INRAB+RAB$W_RSZ 

Set record size 


$UPDATE 

RAB=INRAB 

Write the record 


BLBC 

RO,R.ERR 

Quit on error 


BRW 

READ 

Go back for more 

: Close 

files and exit 


F.ERR: 

PUSHL 

FAB$L_STV+INFAB 

Push STV and STS on 


PUSHL 

FAB$L_STS+INFAB 

stack in reverse order 


CALLS 

BRB 

#2, G'LIB$SIGNAL 

EXIT 

Signal message 

R_ERR: 

PUSHL 

RAB$L_STV+INRAB 

Push STV and STS on 


PUSHL 

RAB$L_STS+INRAB 

stack in reverse order 


CALLS 

#2, G‘LIB$SIGNAL 

Signal message 

DONE: 

SCLOSE 

FAB=INFAB 

Close files 

EXIT: 

RET 

.END 

UPDATE 

Return with status in RO 


This program uses a key and a new record entered from the terminal to 
update a record in the input file. 

To use the $UPDATE macro, the $FAB macro for the file must specify that 
the FAB$V_UPD bit is marked in the file access (FAB$B_FAC) field as shown 
in the following code example: 

INFAB: $FAB FNM=<INFILE:>,- 
FAC=<GET.UPD> 

Before updating a record, the program uses the Find service to locate the 
record by executing the $F1ND macro located at the FIND label. 

$FIND RAB=INRAB 
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4.8 Using Block I/O 

In addition to the major types of record access provided by the sequential, 
random by key value or relative record number, and random by RFA access 
modes, VMS RMS provides another means to access data in a file: block I/O. 

Block I/O operations let you directly read or write the blocks of a file. These 
operations are provided for users who must keep system overhead to a 
minimum and need no interpretation of file data as logical records, yet still 
want to take advantage of the easy file access of VMS RMS. Block I/O is an 
intermediate step between the VMS RMS record operations and direct use of 
VMS $QIO system services. 

The three block I/O services are invoked using the $READ, $SPACE, and 
$WRITE macros, respectively. 

• The Read service transfers a specified number of bytes to memory. 

• The Space service positions a file forward or backward a specified number 
of blocks. 

• The Write service writes a specified number of bytes to a file. 

The Read and Write services always begin on a block boundary. 

In addition to the Read, Space, and Write services, you can use the following 
services on a record stream connected for block I/O operations: 

• The Disconnect service ($DISCONNECT macro) 

• The Flush service ($FLUSH macro) 

• The Next Volume service ($NXTVOL macro) 

• The Rewind service ($REWIND macro) 

These services perform miscellaneous operations or disconnect the record 
stream. They do not work on the contents of the records themselves. 

You cannot perform block I/O operations on shared files. That is, file access 
for block I/O operations is denied unless the FAB$V_UPI or the FAB$V__NIL 
bit is set in the FAB$B_SHR field. 

You specify block I/O operations for a record stream by setting the FAB$V_ 
BIO bit in the file access (FAB$B_FAC) field as input to the Open or Create 
services. If you intend to write to the file, you must set the PUT option in the 
FAB$B_FAC field; if you intend to read from the file, you must set the GET 
option in the FAB$B_FAC field. Setting the FAB$V_BIO bit when you are 
creating a relative or indexed file causes VMS RMS to omit prolog processing 
for indexed files and initial space prezeroing in relative files. 

For files of unknown organization, block I/O is the only form of processing 
allowed. Processing proceeds identically to that for block I/O to the relative 
file organization described above. 


4-23 




VMS RMS Example Programs 

4.8 Using Block I/O 


4.8.1 Mixed Block and Record I/O 

How and when VMS RMS allows you to switch between record I/O and 
block I/O depends on the organization of the file being accessed. 

When you access sequential files, VMS RMS allows you to switch between 
record I/O and block I/O with each record operation, if desired. To enable 
I/O switching for a record stream connected to a sequential file, use the 
following procedure: 

1 Set the FAB$V_-BRO option in the FAB$B_FAC field as input to the 
Create or Open service. 

2 Clear the RAB$L_ROP field RAB$V_BIO option as input to the Connect 
service. 

This procedure informs VMS RMS that it should check the RAB$V_BIO 
option in the RAB$L_ROP field after each operation. 

To do a block I/O operation: 

1 Set the RAB$L_ROP field RAB$V_BIO option. 

2 Invoke a VMS RMS block I/O service (Read, Space, or Write). 

To do a record I/O operation: 

1 Clear the RAB$L_ROP field RAB$V_BIO option. 

2 Invoke a VMS RMS record I/O service. 

Use care if you do choose to mix record and block I/O operations for 
sequential files. When you switch operations on disk devices, the context 
of the current record, the next record, and the next block pointer is undefined. 
Thus, the first operation after the switch must not use sequential record access 
mode. For magnetic tape devices, the context of the next record or next block 
indicates the start of the following block on the tape for the first operation 
after the switch. 

As previously noted, you usually set the FAB$B_FAC field FAB$V-_BRO 
option only to indicate to VMS RMS that you want to mix record I/O and 
block I/O operations. If you decide that you want to perform block I/O 
processing only, you can set the RAB$L_ROP field RAB$V_BIO option after 
you open the file but before you invoke the Connect service. This connect¬ 
time operation overrides the setting of the FAB$V_BRO option for the current 
record stream and indicates to the Connect service that you only intend to 
do block I/O for this file, thus eliminating the need to allocate internal I/O 
buffers. (However, you must still allocate buffers for block I/O operations 
in your application program.) If you set the FAB$V_BRO option when you 
create an indexed file, the key definition XABs for that file must be present. 

When you access relative or indexed files, switching is available only if you 
close and reopen the file. VMS RMS does not permit both types of I/O 
simultaneously. When multiple record streams are used, all record streams 
must use the same type of I/O, either record I/O or block I/O. 

You specify the I/O type when you create or open a file by either selecting 
the block I/O option (FAB$V_BIO bit set) or by selecting record I/O (FAB$V_ 
BIO bit clear). For relative and indexed files, the decision to use block I/O or 
record I/O for a file can be postponed, if desired, until the record stream is 
connected by the following procedure: 
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4.8.2 


1 Set the FAB$B_FAC field FAB$V_BRO option when you are opening (or 
creating) the file. 

2 Indicate the appropriate operation to the Connect service by either setting 
the RAB$V__BIO bit in the RAB$L«>ROP for block I/O or by clearing it 
for record I/O. 


The Next Block Pointer (NBP) 


For block I/O operations to sequential files on disk devices, VMS RMS 
maintains an internal next block pointer (NBP) that does the following 
functions: 

• Points to the beginning of the file following execution of a Connect 
service if the RAB$V_EOF option in the RAB$L-_ROP field of the RAB 
is cleared. If the RAB$L^ROP field RAB$V_EOF option is set, the NPB 
points to the block following the end of file. The RAB$V_EOF option is 
relevant only for sequential files doing block I/O processing. 

• Points to the block following the highest numbered block transferred by a 
read or write operation. 

• Points to the next block following an operation invoked by the Space 
service. 


An explicit Extend service is required for relative and indexed files because 
VMS RMS does not automatically extend a file's allocation when using block 
I/O processing. 

Example 4-9 illustrates how to copy a file using block I/O. 

Example 4—9 Use of Block I/O 


.TITLE 

BLOCKIO 


; This program 

copies the input file to the output file. 

; It illustrates block I/O using the VMS 
; macros. 

RMS $READ and $WRITE 

.PSECT 

DATA.WRT.NOEXE 


INFAB: $FAB 

FNM = <INFILE:>,- 

Input file name 


FAC = <BI0.GET> 

Block I/O read operations 

INRAB: $RAB 

FAB = INFAB.- 

Pointer to FAB 


BKT = 0.- 

Start with current block 


UBF = REC.BUFF,- 

Record buffer 


USZ = REC.SIZE 

and size 

OUTFAB: $FAB 

FNM = <0UTFILE:>,- 

Output file name 


FOP = CBT,- 

Try for contiguous file 


MRS = REC.SIZE,- 

Maximum record size 


FAC = <BI0.PUT>,- 

Block I/O write operations 


RAT = CR 

Implied carriage control 

OUTRAB: $RAB 

FAB = OUTFAB.- 

Pointer to FAB 


BKT = 0.- 

Start with current block 


RBF = REC.BUFF 

Output uses same buffer 


REC.SIZE = 1024 


as input 

Maximum record size 


Example 4-9 Cont'd. on next page 
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Example 4-9 (Cont.) Use of Block I/O 


REC.BUFF: 




.BLKB 

REC.SIZE 

; Record buffer 


.PSECT 

CODE.NOWRT.EXE 


; Initialization - Open input and output 

files and connect streams 


.ENTRY 

BL0CKI0.‘'M<> 

No registers to save 


$0PEN 

FAB=INFAB 

Open input file 


BLBC 

RO.EXITl 

Quit on error 


$C0NNECT RAB=INRAB 

Connect to input 


BLBC 

RO,EXIT2 

Quit on error 


MOVE 

INFAB+FAB$L_ALQ,- 

Set proper size 



OUTFAB+FAB$L_ALQ 

for output 


$CREATE FAB=OUTFAB 

Create output file 


BLBC 

RO.EXITS 

Quit on error 


SCONNECT RAB=OUTRAB 

Connect to output 


BLBC 

R0,EXIT4 

Quit on error 

; Copy loop 



READ: 

$READ 

RAB=INRAB 

Get a block 


BLBS 

RO.WRITE 

Write the block 


CMPL 

RO.#RMS$_EOF 

Was error end-of-file? 


BEQL 

DONE 

Successful completion 


BRB 

EXIT2 

If not. signal error 

WRITE: 

MOVW 

INRAB+RAB$W_RSZ. - 

Set the record size 



OUTRAB+RAB$W_RSZ 

for output 


$WRITE 

RAB=OUTRAB 

Write the block 


BLBC 

R0.EXIT4 

Quit on error 


BRB 

READ 

Go back for more 

; Error 

Signaling 


EXITl: 

MOVE 

INFAB+FAB$L_STS.R2 

Move STS into R2 


MOVE 

INFAB+FAB$L_STV.R3 

Move STV into RS 


BRB 

EXIT 

Signal error 

EXIT2: 

MOVE 

INRAB+RAB$L_STS,R2 

Move STS into R2 


MOVE 

INRAB+RAB$L_STV,R3 

Move STV into RS 


BRB 

EXIT 

Signal error 

EXITS: 

MOVE 

OUTFAB+FAB$L_STS, R2 

Move STS into R2 


MOVE 

0UTFAB+FAB$L_STV.R3 

Move STV into RS 


BRB 

EXIT 

Signal error 

EXIT4: 

MOVE 

OUTRAB+RAB$L.STS.R2 

Move STS into R2 


MOVE 

0UTRAB+RAB$L_STV.R3 

Move STV into RS 


BRB 

EXIT 

Signal error 

; Close 

files and exit 


DONE: 

$CL0SE 

FAB=INFAB 

Close input and 


SCLOSE 

FAB=OUTFAB 

output files 


RET 


Return w/ success in RO 

EXIT: 

PUSHL 

RS 

Push STV and STS 


PUSHL 

R2 

on stack 


CALLS 

#2. GUIBSSIGNAL 

Signal error 


RET 


Return w/ status in RO 


.END 

BLOCKIO 
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This example program uses block I/O to transfer the contents of the input file 
to the output file. The following program data statements specify block I/O 
read operations from the input file by setting the FAB$V_BIO bit (block I/O) 
and the FAB$V_GET bit (read) in the FAB$B_FAC field of the input file's 
FAB: 

INFAB: $FAB FNM = <INFILE>. - ;Input file name 

FAC = <BI0.GET>.- 

The following data statements specify block I/O write operations to the 
output file by setting the FAB$V_BIO bit (block I/O) and the FAB$V_PUT bit 
(write) in the FAB$B_FAC field of the output file's FAB: 

OUTFAB: $FAB FNM = <INFILE>, - ;Output file name 

FAC = <BI0,PUT>.- 

The input file's contents are copied until the end of file is encountered. Any 
errors are signaled with the convention of using both the STS and STV fields 
of the appropriate control block. 


4.9 



4.10 


Other Record-Processing Operations 

See Part III for details of VMS RMS record services not discussed in this 
chapter, including the Flush, Free, Next Volume, Release, Rewind, and 
Wait services. A process invokes these services using the $FLUSH, $FREE, 
$NXTVOL, $RELEASE, $REWIND, and $WAIT macros, respectively. 


Control Routines 


In addition to the general- and special-purpose file-processing macros, VMS 
RMS provides three control routines for processing files. These routines are 
identified by the following entry point names: 

• SYS$RMSRUNDWN 



SYS$SETDDIR 

SYS$SETDFPROT 


These routines do not reference fields in user control blocks and are not called 
with a macro. Instead, you provide an argument list and call VMS RMS at 
the entry point for the routine. None of these routines is widely used, and 
none is essential to normal VMS RMS file and record processing. 


For information on these routines, see the VMS System Services Reference 
Manual. 
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5 File Access Block (FAB) 


The file access block (FAB) defines file characteristics, file access, and certain 
run-time options. It also indicates whether other control blocks are associated 
with the file. 


5.1 Summary of Fields 

Certain FAB fields are directly equivalent to certain File Definition Language 
(FDL) attributes. For information about FDL, refer to the VMS File Definition 
Language Facility Manual. 

The symbolic offset, size, FDL equivalent, and a brief description of each FAB 
field are presented in Table 5-1. 

Table 5~1 FAB Fields 


Size 

Field Offset (Bytes) FDL Equivalent Description 


FAB$L_ALQ 

4 

FILE ALLOCATION 

Allocation quantity (blocks) 

FAB$B_BID’ 

1 

None 

Block identifier 

FAB$B_BKS 

1 

FILE BUCKET_SIZE 

Bucket size 

FAB$B_BLN’ 

1 

None 

Block length 

FAB$W_BLS 

2 

FILE MT_BLOCK_SIZE 

Magnetic tape block size 

FAB$V_CHAN_MODE 

_2 

None 

Channel access mode 
protection 

FAB$L_CTX 

4 

FILE CONTEXT 

Context 

FAB$W_DEQ 

2 

FILE EXTENSION 

Default file extension quantity 

FAB$L_DEV^ 

4 

None 

Device characteristics 

FAB$L_DNA 

4 

FILE DEFAULT_NAME 

Default file specification string 
address 

FAB$B_DNS 

1 

FILE DEFAULT_NAME 

Default file specification string 
size 

FAB$B_FAC 

1 

ACCESS^ 

File access 

FAB$L_FNA 

4 

FILE NAME 

File specification string address 

FAB$B_FNS 

1 

FILE NAME 

File specification string size 

FAB$L_FOP 

4 

FILE^ 

File-processing options 

FAB$B_FSZ 

1 

RECORD CONTROL _FIELD_SIZE 

Fixed-length control area size 

FAB$W_GBC 

2 

FILE GLOBAL_BUFFER_COUNT 

Global buffer count 


^This field is statically initialized by the $FAB macro to identify this control block as a FAB. 

^This is a 2-bit field. 

^This field cannot be initialized by the $FAB macro. 

^This field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 5-1 (Cont.) 

FAB Fields 




Size 



Field Offset 

(Bytes) 

FDL Equivalent 

Description 

fab$w_ifP 

2 

None 

Internal file identifier 

FAB$V_LNM_MODE 

_2 

None 

Logical name translation access 
mode 

FAB$L_MRN 

4 

FILE MAX_RECORD_NUMBER 

Maximum record number 

FAB$W_MRS 

2 

RECORD SIZE 

Maximum record size 

FAB$L_NAM 

4 

None 

Name block address 

FAB$B_ORG 

1 

FILE ORGANIZATION 

File organization 

FAB$B_RAT 

1 

RECORD^ 

Record attributes 

FAB$B_RFM 

1 

RECORD FORMAT 

Record format 

FAB$B_RTV 

1 

FILE WINDOW_SIZE 

Retrieval window size 

FAB$L_SDC^ 

4 

None 

Secondary device 
characteristics 

FAB$B_SHR 

1 

SHARING'* 

File sharing 

FAB$L_STS3 

4 

None 

Completion status code 

FAB$L_STV^ 

4 

None 

Status values 

FAB$L_XAB 

4 

None 

Extended attribute block 
address 


^This is a 2-bit field. 

^This field cannot be initialized by the $FAB macro. 

"^This field contains options; corresponding FDL equivalents are listed in the description of the field. 


Each FAB field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations on remote files with a VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual 

To use a FAB, you must allocate process storage and specify the character 
string for the primary file specification and, optionally, the default file 
specification. The FAB$L_FNA and FAB$B_FNS fields define the primary 
file specification to VMS RMS; the FAB$L_DNA and FAB$B_DNS fields 
define the default file specification to VMS RMS. 

The format and arguments of the $FAB macro and the $FAB_STORE macro 
are defined in Appendix B. 
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File Access Block (FAB) 

5.2 FAB$L_ALQ Field 


FAB$L_ALQ Field 

The allocation quantity (ALQ) field defines the number of blocks to be 
initially allocated to a disk file when it is created (using a Create service) or to 
be added to the file when it is explicitly extended (using an Extend service). 
This field corresponds to the FDL attribute FILE ALLOCATION. 

This field contains a numeric value in the range of 0 through 4,294,967,295, 
although the maximum value depends on the number of blocks available on 
the device to be used. A value of 0 indicates no allocation. 

When you create a new file using the Create service, VMS RMS interprets the 
value in the FAB$L_ALQ field as the number of blocks for the initial extent 
of the file. If the value is 0, the minimum number of blocks for the specific 
file organization is the allocation quantity used for the initial extent. For 
example, in indexed files, only the number of blocks necessary to contain key 
and area definitions is used as the initial extent quantity when FAB$L^LQ 
is 0. 

When VMS RMS opens an existing file, it sets the FAB$L_ALQ field to 
indicate the highest virtual block number currently allocated to the file. 

When you use the Extend service, this field specifies the number of blocks to 
be added to the file. Note that VMS RMS uses this value as the extension 
value when a process extends a file using the Extend service unless the 
process changes the value before it invokes the Extend service. 

Note that the value 0 is not acceptable for extending a file. 

When you use the Create and Extend services, the allocation quantity value is 
rounded up to the next disk cluster boundary; the number of blocks actually 
allocated is returned in the FAB$L_ALQ field. 

Note that the function of the FAB$L_ALQ field with the Create and Extend 
services changes if allocation control XABs are present during the operation. 
The description of the XABALL control block (see Chapter 8) discusses 
allocation control XABs and their effect on the FAB$L_j\LQ field during file 
creation or extension. 


FAB$B_BID Field 


The block identifier (BID) field is a static field that identifies a control block 
as a FAB. Once set, this field should not be altered unless the control block 
is no longer needed. This field must be initialized to the symbolic value 
FAB$C_BID (this is done by the $FAB macro). 


5.4 



FAB$B_BKS Field 

The bucket size (BKS) field is used only for relative or indexed files to specify 
the number of blocks in each bucket of the file. 

This field contains a numeric value in the range of 0 to 63. If you do not 
specify a value or specify a value of 0, VMS RMS uses a default of the 
minimum number of blocks needed to contain a single record, or a minimum 
of two records for indexed files. If the file will be processed by RMS-11, the 
bucket size must be less than or equal to 32 blocks. 
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When calculating the bucket size, you must consider the control information 
(overhead) associated with each bucket. Also, certain record types contain 
control bytes; thus, the number of records per bucket multiplied by the 
number of control bytes per record equals the number of record overhead 
bytes per bucket. See the Guide to VMS File Applications for more information. 

Before specifying a bucket size, you must be aware of the relationship 
between bucket size and record size. You must also consider any record 
control bytes (overhead) required by VMS RMS for the type of record chosen. 
Because VMS RMS does not allow records to cross bucket boundaries, you 
must ensure that the number of blocks per bucket conforms to formulae 
designed to handle one of the following: 

• Relative files with fixed-length records 

• Relative files with variable-length records 

• Relative files with VFC (variable with fixed control) records 

• Indexed files with fixed-length records 

• Indexed files with variable-length records 

You can use the Edit/FDL Utility to determine the optimum bucket size. 
Note that if an allocation control XAB is specified, the value specified in the 
XAB$B_BKZ field supersedes the value specified in the FAB$B_BKS field. 
When multiple allocation control XABs are specified, the largest value in any 
XAB$B__BKZ field supersedes the value in the FAB$B JKS field. Refer to 
Chapter 8 for information about the XAB$B-_BKZ field. 

When you open an existing relative or indexed file, VMS RMS sets the 
FAB$B_BKS field to the defined size of the largest bucket size in the file. 
However, when you create a new relative or indexed file, set the FAB$B-.-BKS 
field before you invoke the Create service rather than use the default. 

With indexed files, note that if the FAB$B_BKS field is not specified and a 
maximum record size (FAB$W._MRS field) is specified, then VMS RMS selects 
a bucket size that allows at least one maximum size record to fit. Generally, 
performance for record insertion and sequential retrieval on the primary key 
improves if at least six or seven data records fit into a primary data bucket. 

If either the bucket size or the disk cluster size is other than one block, use a 
default extension quantity (FAB$W-_DEQ) that is the least common multiple 
of the bucket size and cluster size to avoid allocated but unused blocks within 
the file. 

This field corresponds to the FDL attribute FILE BUCKET_SIZE. 


5.5 FAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
FAB. Once set, this field should not be altered unless the control block is no 
longer needed. This field must be initialized to the symbolic value FAB$C__ 
BLN (this is done by the $FAB macro). 
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5.6 FAB$W-BLS Field 

VMS RMS uses the block size (BLS) field as input for nondisk files. The 
BLS field usually defines the size, in bytes, of the blocks on a magnetic tape. 
Note that for some devices, this value must be an even number. This field 
corresponds to the FDL attribute FILE MT_BLOCK_SIZE. 

The FAB$W_BLS field contains a numeric value in the range of 20 through 
65,535 for ANSI-formatted tapes and 14 through 65,532 for foreign tapes. 
(Foreign tapes are those that are not in the standard ANSI format used by 
the VMS operating system and must be mounted using the DCL command 
MOUNT/FOREIGN.) If no value or a value of 0 is specified, the default 
selected when the volume was mounted is used. 

When you create a magnetic tape file, you can set the FAB$W_BLS field 
before you invoke the Create service. In all other cases, VMS RMS ignores 
this field. When you open an existing sequential file with an Open service, 
VMS RMS returns the device buffer size. For terminals, this field defines the 
WIDTH setting; for mailboxes, this field defines the maximum message size. 

For compatibility with RMS-11, VMS RMS always rounds off the block size 
for an ANSI-formatted tape to the next highest multiple of 4. For example, 
if you set the block length to 38, VMS RMS sets it to 40. The block size of a 
foreign tape is not rounded off by VMS RMS. 

To create a magnetic tape for interchange with DEC operating systems other 
than VMS, consult the documentation for the recipient system to identify 
possible limitations on block size. ANSI standards require that the block size 
be less than or equal to 2048 bytes. 


5.7 FAB$V_CHAN_MODE Subfield 

The channel access mode protection (CHAN_MODE) subfield is the 
component part of the FAB$B_ACMODES field that specifies the access 
mode in which the requested channel is assigned. VMS RMS ignores this 
2-bit field unless the process first sets either the FAB$V_UFO bit or the 
FAB$V->NFS bit in the FAB$L_FOP field. 

The FAB$V__CHAN-_MODE subfield may contain one of the four values 
listed below with the related constant value for each shown in parentheses. 

0 None 

1 Executive mode (PSL$C_EXEC) 

2 Supervisor mode (PSL$C_SUPER) 

3 User mode (PSL$C_USER) 

The default value is 0 (none), which is interpreted by VMS RMS as executive 
mode. 

If the access mode requested is more privileged than the access mode of the 
calling process, VMS RMS uses the access mode of the caller and does not 
return an error. For more information about logical name concepts, see the 
VMS System Services Volume. 

There is no corresponding FDL equivalent for this field. The FAB$V_CHAN_ 
MODE subfield is used locally for channel to DECnet communications but is 
ignored on the remote system. 
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To set this field from MACRO level, you include the appropriate expression as 
an argument to the $FAB macro. For example, to specify supervisor channel 
access mode, you might include a statement in this format: 

$FAB ...,CHAN.MODE = PSC$C_SUPER_ 

From a high-level language, refer to your documentation as to how (and 
whether) you can directly access VMS RMS fields and then incorporate the 
appropriate channel access mode expression into the appropriate language 
statement. 


5.8 FAB$L_CTX Field 

The user context (CTX) field allows you to convey user information to a 
completion routine in your program. This field contains a user-specified 
value, up to four bytes long, and is intended solely for your use. VMS RMS 
never uses it for record management activities. 

This field corresponds to the FDL attribute FILE CONTEXT. 


5.9 FAB$W_DEQ Field 

The default file extension quantity (DEQ) field specifies the number of blocks 
to be added when VMS RMS automatically extends the file. Automatic 
extension only applies to files that reside on disk devices and occurs whenever 
your process invokes a Put or Write service and the currently allocated file 
space is exhausted. When you invoke a Put service, automatic file extension 
occurs when needed, regardless of the file organization. When you invoke 
the Write service, automatic extension occurs only for sequential files (indexed 
and relative files require the Extend service to extend file allocation). 

This field corresponds to the FDL attribute FILE EXTENSION. 

This field contains a numeric value in the range 0 through 65,535, which 
is rounded up to the next cluster boundary. A large value results in fewer 
file extensions over the life of a file; a small value results in numerous file 
extensions over the life of a file. When a file has numerous file extensions 
that may be noncontiguous, this slows record access. 

For file creation, if you do not specify a value or specify 0, VMS RMS uses 
the default specified by the DCL command SET RMS_DEFAULT/EXTEND^ 
QUANTITY. If this value is also 0, then VMS RMS uses the system default 
extension quantity specified by the SYSGEN parameter RMS_EXTEND_SIZE. 
If this value is 0, then VMS RMS computes the default value. 

When the value in this field, the value set by the SET RMS—DEFAULT 
/EXTEND—QUANTITY command, and the value of the SYSGEN parameter 
RMS—EXTEND_SIZE are all 0, VMS RMS calculates what is often a large 
value to minimize the number of extend operations that it must perform. At 
times, this value can exceed the available disk quota even though there is 
actually enough space for the file if only the required amount is used. You 
can use the DCL command SET RMS-DEFAULT/EXTEND-QUANTITY to 
limit (explicitly specify) the extension size to the recommended number of 
blocks. An appropriate size is the number of blocks specified as the cluster 
size for the device (set by the DCL command INITIALIZE/CLUSTER—SIZE). 
For large files on a volume where there is sufficient disk space, consider using 
a multiple of the cluster size to improve subsequent performance. 
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When creating a new file, you can specify the extension quantity for the file 
by setting the desired value in the FAB$W_DEQ field before or after issuing a 
Create service. This value becomes a permanent attribute for the file. 

When processing an existing file, you can temporarily override the default 
extension quantity specified when the file was created. To do this, set the 
desired value before or after issuing the Open service. Once the file is closed, 
the default extension quantity reverts to the value set when the file was 
created. 

See the discussion under FAB$B__BKS for indexed files. 

Note that the use of an allocation control XAB overrides the value in this 
field. See Chapter 8 for a detailed description of allocation control XABs. 


5.10 FAB$L_DEV Field 

The device characteristics (DEV) field allows your program to obtain the 
generic characteristics of the device containing the file. You can locate and 
test the various bits in the field using symbolic offsets. This is a binary 
options field set by VMS RMS when you invoke an Open, Create, Display, or 
Parse service (this is set by the Parse service only if the NAM$V_SYNCHK 
option in the NAM$B_NOP field is clear). 

Table 5-2 describes the bits in the device characteristics field. Each bit 
has its own symbolic bit offset and mask value. These definitions are 
made available to your program by referring to the $DEVDEF macro in 
SYS$LIBRARY:STARLET.MLB. The symbolic bit offset is formed by prefixing 
the characteristic name with DEV$V_. The mask value is formed by prefixing 

the characteristic name with DEV$M_For example, the DEV$V_>REC bit has 

a mask value of DEV$M_REC. 


Table 5-2 

Device Characteristics 


Bit Offset 

Description 


DEV$V_ALL 

Device is allocated. 


DEV$V_AVL 

Device is available for use. 


DEV$V_CCL 

Carriage control device. 


DEV$V_CDP 

Device has dual access paths, one 
using an MSCP server. 

of which is a remote node 

DEV$V_CLU 

Device is available on a VAXcluster 


DEV$V_DET 

Terminal device is detached. 


DEV$V_DIR 

Directory-structured device. 


DEV$V_DMT 

Device is marked for dismount. 


DEV$V_DUA 

Device has dual access paths, both 
driver. 

of which use a disk class 

DEV$V_ELG 

Device is error log enabled. 


DEV$V_FOD 

File-oriented device (disk and magnetic tape). 

DEV$V_FOR 

Device is mounted foreign (non-file- 

structured). 

DEV$V_GEN 

Device is a generic device. 
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Table 5-2 (Cont.) Device Characteristics 


Bit Offset Description 


DEV$V_IDV 

DEV$V_MBX 

DEV$V_MNT 

DEV$V_NET 

DEV$V_ODV 

DEV$V_OPR 

DEV$V_RCK 

DEV$V_RCT 

DEV$V_REC 


DEV$V_RND 

DEV$V_RTM 

DEV$V_RTT 

DEV$V_SDI 

DEV$V_SHR 

DEV$V_SPL 

DEV$V_SQD 

DEV$V_SWL 

DEV$V_TRM 

DEV$V_WCK 


Device can provide input. 

Device is a mailbox. 

Device is currently mounted. 

Network device. 

Device can accept output. 

Device has been enabled as an operator console terminal. 

Device has read-check enabled. 

Disk device is an RA80, RA81, RA82 or RA60. 

Record-oriented device (terminal, mailbox, line printer, for 
example). If field is 0, device is assumed to be block-oriented 
(disk device or magnetic tape device). All record-oriented 
devices are considered sequential In nature. 

Device Is random access In nature (disk). 

Device is real-time In nature; not suitable for use by VMS RMS. 
Terminal device is a remote terminal (DCL command SET HOST). 
Single directory device (master file directory only). 

Shareable device. 

Device is being spooled. 

Sequential block-oriented device (magnetic tape). 

Device is currently software write-locked. 

Terminal device. 

Device has write-check enabled. 


For DECnet operations, this field represents the actual characteristics of the 
target device when a Create, Open, or Display service is invoked. It is not 
filled in when a Parse service is invoked using a file specification that contains 
a node name. 


5.11 FAB$L_DNA Field 

The default file specification string address (DNA) field provides the address 
of a file specification string VMS RMS uses to apply defaults for any missing 
components of the file specification. This field works with the FAB$B_DNS 
field, which initializes the default file specification string size, to provide a 
default file specification string. Defaults are applied after VMS RMS examines 
the primary file specification string that the FAB$L_FNA field (described 
below) points to. 

This field and the FAB$B_DNS field correspond to the FDL attribute FILE 
DEFAULT_NAME. 

The FAB$L_DNA field contains the symbolic address of a default file 
specification string, which is an ASCII string containing one or more 
components of a file specification. The components in the string must be 
in the order in which they would occur in a complete file specification. 
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The default file specification string is used primarily when a process accepts 
file specifications interactively; normally, file specifications known to a user 
program are specified completely in the FAB$L_FNA and FAB$B_FNS fields, 
You can specify defaults for one or more of the following file specification 
components: 

• Node 

• Device 

• Directory 

• File name 

• File type 

• File version number 

The default file specification string is used only if components are missing 
from the string whose address is stored in the FAB$L_FNA field and those 
components are present in the default file specification string. 

If you use VAX MACRO, you can use the DNM keyword to specify the 
FAB$L_DNA and FAB$B_DNS fields. 


5.12 FAB$B_DNS Field 

The default file specification string size (DNS) field indicates the size, in bytes, 
of the string whose address is contained in the FAB$L_DNA field. This field 
contains a numeric value in the range 1 to 255. 

This field and the FAB$L_DNA field correspond to the FDL attribute FILE 
DEFAULT_NAME. 

5.13 FAB$B_FAC Field 

The file access (FAC) field specifies the operations and services a process is 
seeking to use in accessing a file. RMS uses this field, together with the share 
field (SHR) in each potential accessor's FAB, to determine whether or not 
to permit a process to access a file. The FAC field corresponds to the FDL 
primary attribute ACCESS. 

Within the FAC field, each bit position corresponds to an operation or service 
option that the process intends to use when accessing the file. In this manner, 
a process may specify several options, assuming they are compatible, by 
setting the appropriate bits. Each option has its own symbolic bit offset and 
mask value. For example, the GET service option has a symbolic bit offset of 
FAB$V-.GET and a mask value of FAB$M_GET. 

When RMS attempts to open a file for a process, it examines the process's 
FAB$B_FAC field to determine what operations or services the process is 
seeking to use in conjunction with the file access. 

VMS RMS determines whether or not the process seeking access to the file 
intends to use operations and services that are compatible with the sharing 
options permitted by processes currently accessing the file. It checks the FAC 
field of the requesting process to determine whether it requires read or write 
access to the file. It then checks the SHR field of the requesting process to 
determine whether it will share read or write access with other processes that 
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are accessing the file. A read (GET) implies read access. Delete (DEL), write 
(PUT), truncate (TRN), and update (UPD) all imply write access. 

For example, assume that Process A opens the file for GET access (FAC=GET) 
and is willing to share the file with processes that are doing GET and PUT 
accesses (SHR=GET,PUT). Since this is the only process accessing the file, 
RMS permits it to read access the file. 

Assume that a second process. Process B, wants to access the same file doing 
PUT accesses (FAC=PUT) and is willing to share the file with processes 
doing GET accesses and PUT accesses (SHR=GET,PUT). Because Process B is 
compatible with Process A (they both agree to share the file with any process 
that is doing either GET accesses or PUT accesses), VMS RMS permits the 
second process to access the file. 

Now assume that a third process. Process C, wants GET access (FAC=GET) to 
the same file but will share the file only with processes doing GET accesses 
(SHR=GET). Although Process C is compatible with Process A (FAC=GET), it 
is not compatible with Process B (FAC=PUT), so RMS denies Process C access 
to the file. Conversely, if C tries to access the file before B, C gets access and 
B is denied access. 

VMS RMS always grants file access to the first process accessing a file, 
assuming no security access restrictions exist. When a process acquires access 
to a file, RMS rejects any attempt to use a service not included in the initial 
access request. 

The FAB$B_FAC field options are listed below. 

Options 

FAB$V^BIO 

Requests file access for doing block I/O operations that use Read (FAB$V— 
GET), Write (FAB$V-_PUT) or the Space services. Specifying block I/O 
prohibits the use of record I/O operations (such as the (3et, Put, Update, 
Delete, or Truncate services). 

This option corresponds to the FDL attribute ACCESS BLOCK JO. 

FAB$V_BRO 

Requests file access for doing either block I/O or record I/O as determined 
by the state of the RAB$V_BIO bit in the RAB at connect time. For additional 
information, see Section 4.8, under the discussion of block I/O, and 
Section 7.19. 

This option corresponds to the FDL attribute ACCESS RECORD JO. 

FABSV^DEL 

Requests file access for invoking the Delete service (or the equivalent VAX 
language statement that deletes a record). This option applies only to relative 
and indexed files. 

This option corresponds to the FDL attribute ACCESS DELETE. 

FAB$V-_GET 

Requests file access for invoking either the Get or Find service (or equivalent 
VAX language statement that reads a record). This is the default if a process 
requests access to a file without including FAB$B_-FAC field information or if 
the FAB$V_DEL, FAB$V_UPD, or FAB$V^TRN option is set in the FAB$B_ 
SHR field. If the process takes the FAB$V_GET option together with either 
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the FAB$V_BIO option or the FAB$V__BRO option, it can invoke the Read 
service. 

This option corresponds to the FDL attribute ACCESS GET. 

FAB$V_PUT 

Requests file access for invoking either the Put or Extend service (or the 
equivalent VAX language statement that writes a record or extends a file). 
This is the default when a process creates a file. If the process takes the 
FAB$V_PUT option together with either the FAB$V_BIO option or the 
FAB$V_BRO option, it can invoke the Write service. 

This option corresponds to the FDL attribute ACCESS PUT. 

FAB$V-TRN 

Requests file access for invoking the Truncate service (or the equivalent VAX 
language statement that truncates a file). Also allows use of the RAB$L__ROP 
truncate-on-put (RAB$V_TPT) option with the Put and Write service. This 
option applies only to sequential files. 

This option corresponds to the FDL attribute ACCESS TRUNCATE. 

FAB$V_UPD 

Requests file access for invoking either an Update or Extend service (or the 
equivalent VAX language statement that rewrites a record or extends a file). 
Also allows use of the RAB$L—ROP update-if (RAB$V_UIF) option for the 
Put service. 

This option corresponds to the FDL attribute ACCESS UPDATE. 


5.14 FAB$L_FNA Field 

The file specification string address (FNA) field works with the FAB$B_FNS 
field to specify the primary file specification of the file to be processed. If this 
string does not contain all the components of a full file specification, VAX 
RMS uses the defaults supplied in the default file specification string (see 
FAB$L_DNA and FAB$B_DNS). If no default string is present or if the file 
specification is still incomplete, VMS RMS provides additional defaults. 

This field contains the symbolic address of a file specification string, which 
is an ASCII string containing one or more components of a file specification. 
This field is used as input by many file-processing services. To obtain the file 
specification returned by VMS RMS after it translates any logical names and 
applies defaults, a NAM block must be present (see FAB$L_NAM). 

If you use VAX MACRO, you can use the FNM keyword to specify the 
FAB$L_FNA and FAB$B_FNS fields. 

This field and the FAB$B—FNS field correspond to the FDL attribute FILE 
NAME. 
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5.15 FAB$B_FNS Field 

The file specification string size (FNS) field specifies the size, in bytes, of the 
ASCII file specification string, whose address is contained in the FAB$L_FNA 
field. This field contains a numeric value in the range of 0 through 255. 

This field and the FAB$L_FNA field correspond to the FDL attribute FILE 
NAME. 


5.16 FAB$L_FOP Field 

FAB$L_FOP is the symbolic offset value for the FAB's file-processing options 
(FOP) field. This field specifies which of the various optional file operations 
are to be implemented for the process. 

The FOP is a 32-bit field in which each file-processing option has a 
corresponding bit assignment to let you specify multiple options (multiple 
bits can be set), when applicable. Each option has a unique symbolic offset 
value and mask value but you need only specify the appropriate 3-letter 
mnemonic when coding a function. For example, the spool-file-on-close 
option has a symbolic offset value of FAB$V_SPL but to specify the option, 
you use the following MACRO statement: 

F0P=SPL 

As detailed in the appropriate descriptions, the only file-processing option 
bits that may be affected by VMS RMS services are the FAB$V_CBT, FAB$V_- 
CTG, FAB$V_RCK, and FAB$V_WCK bits. 

This section presents the file-processing options alphabetically within the 
various functional categories, of which there are seven: 

• Allocation and extension options 

• Performance options 

• Reliability options 

• File name parsing modifiers 

• File disposition options 

• Magnetic tape processing options 

• Nonstandard processing options 

Table 5-3 lists each of the options alphabetically by category. 


Table 5-3 File Processing Options 


Option 

Symbolic Offset 

Allocation and Extension Options 

Contiguous best try 

FAB$V_CBT 

Contiguous allocation 

FAB$V_CTG 

Truncate at end of file 

FAB$V_TEF 
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Table 5-3 (Cont.) File Processing Options 


Option 

Symbolic Offset 

Performance Options 

Asynchronous operation 

FAB$V_ASY 

Deferred write 

FAB$V_DFW 

Sequential only 

FAB$V_SQO 

Synchronous status 

FAB$V_SYNCSTS 


Reliability Options 


Read-check 

FAB$V_RCK 

Write-check 

FAB$V_WCK 


File Name Parsing Modifier Options 


Create-if 

FAB$V_CIF 

Maximum version number 

FAB$V_MXV 

Use NAM block inputs 

FAB$V_NAM 

Output file parse 

FAB$V_OFP 

Supersede existing file 

FAB$V_SUP 

File Disposition Options 

Delete on close 

FAB$V_DLT 

Submit command file on close 

FAB$V_SCF 

Spool file on close 

FAB$V_SPL 

Temporary marked for delete 

FAB$V_TMD 

Temporary file 

FAB$V_TMP 


Magnetic Tape Options 


Do not set to EOF 

FAB$V_NEF 

Current position 

FAB$V_POS 

Rewind file on close 

FAB$V_RWC 

Rewind file on open 

FAB$V_RWO 

Nonstandard Options 

Non-file-structured 

FAB$V_NFS 

User file open 

FAB$V_UFO 


This field corresponds to the FDL primary attribute FILE. 
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Allocation and Extension Options 
FAB$V_CBT 

Contiguous best try; indicates that the file is to be allocated contiguously 
on a "best effort" basis. It is input to the Create service and output from 
the Open service to indicate the file status. Note that the FAB$V_CBT bit 
remains set only if allocation using one, two, or three extents is actually 
performed. That is, the FAB$V_CBT bit is switched off before the return from 
the Create service unless VMS RMS can allocate the file within three extents. 
The FAB$V_CBT option overrides the FAB$V_CTG option. Note that this 
option is ignored if multiple areas are defined for an indexed file. 

This option corresponds to the FDL attribute FILE BEST_TRY— 
CONTIGUOUS. 

FAB$V«CTG 

Contiguous; indicates that the space for the file is to be allocated contiguously. 
If this cannot be done, the operation fails. It is input to the Create service 
and is output by the Open service to indicate the status of the file. Note that 
this option is ignored if multiple areas are defined for an indexed file. The 
FAB$V_CBT option overrides the FAB$V__CTG option. 

This option corresponds to the FDL attribute FILE CONTIGUOUS. 

FABSV^TEF 

Truncate at end of file; indicates that unused space allocated to a file is to be 
deallocated on a Close service. The FAB$V__TEF option applies to unshared 
sequential files. 

This option corresponds to the FDL attribute FILE TRUNCATE_ON_CLOSE. 

Performance Options 
FAB$V_ASY 

Asynchronous; indicates that the specified task is to be done asynchronously. 
The FAB$V__ASY option is relevant only to tasks that involve I/O operations 
and is ignored for process permanent files. The asynchronous I/O option is 
typically used with success/error ASTs, or in conjunction with the $WAIT 
service, to synchronize the program with task completion. When you specify 
FAB$V_ASY, you pass the address of the FAB as an argument to the AST 
routine and VMS RMS returns control to your program immediately. 

FAB$V_DFW 

Deferred write; indicates that writing back to the file of modified I/O buffers 
is to be deferred until the buffer must be used for other purposes. This option 
applies to relative files, indexed files and sequential files opened for shared 
access. 

This option corresponds to the FDL attribute FILE DEFERRED—WRITE and is 
not supported for DECnet operations. 

FAB$V«SQO 

Sequential only; indicates that the file can be processed only in a sequential 
manner, permitting certain processing optimizations. Any attempt to perform 
random access results in an error. The FAB$V_SQO option is input to the 
Create and Open services. 
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This option corresponds to the FDL attribute FILE SEQUENTIAL «_ONLY. 

Note: For DECnet operations, this option enables file transfer mode for Get, Put, 
Read, and Write services. File transfer mode is a Data Access Protocol 
(DAP) feature that allows several records to be transferred in a single¬ 
network I/O operation to maximize throughput for single-direction, 
sequential access file transfer. 

FAB$V_SYNCSTS 

When you select this option, VMS RMS returns the success status RMS$-_ 
SYNCH if the requested service completes its task immediatly. The most 
common reason for not completing a task immediatly is that the task involves 
I/O operations. 

The status RMS$_SYNCH is returned in RO. Refer to the FAB$L_STS field 
for the actual success status or failure status of the task. 

The FAB$V_SYNCSTS option is best used in conjunction with the FAB$V_ 
ASY option. 

Reliability Options 
FAB$V^RCK 

Read-check; specifies that transfers from disk volumes are to be checked by a 
read-compare operation, which effectively doubles the amount of disk I/O at 
some increase in reliability. This option is an input to the Open and Create 
services. If FAB$V_RCK is set, then checking is performed for the duration 
of the access. The FAB$V-_RCK option is also an output of the Open service, 
which indicates the default for the file. This option is not available for RXOl 
and RX02 devices, or for any device that has been mounted using the DCL 
command MOUNT/FOREIGN. 

This option corresponds to the FDL attribute FILE READ__CHECK. 

FAB$V_WCK 

Write-check; indicates that transfers to disk volumes are to be checked by a 
read-compare operation. The FAB$V_WCK option is similar to the FAB$V_ 
RCK option. This option is not available for RXOl and RX02 devices, or 
for any device that has been mounted using the DCL command MOUNT 
/FOREIGN. 

This option corresponds to the FDL attribute FILE WRITE—CHECK. 

File Name Parsing Modifiers 
FAB$V_CIF 

Create if nonexistent; opens an already existing file if it exists. If the file does 
not exist, it is created and the alternate success status RMS$—CREATED is 
returned to indicate that the file was created, not just opened. The FAB$V— 
CIF option is input only to the Create service and overrides the FAB$V—SUP 
option. When the create-if option is used with a search list logical name and 
the file is not found in any of the file specifications supplied using the search 
list, the file is created using the file specification from the first element of the 
search list. 

This option corresponds to the FDL attribute FILE CREATE—IF. 
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FAB$V_MXV 

Maximize version number; indicates that the version number of the file 
should be the maximum of the explicit version number given in the file 
specification, or one greater than the highest version number for an existing 
file in the same directory with the same file name and file type. This option 
enables you to create a file with a specific version number (if the requested 
version number is greater than that of the existing file) or a file with a version 
number that is one higher than the existing file's version number. 

This option is used as input to the Create service only and it corresponds to 
the FDL attribute FILE MAXIMIZE ^VERSION (default is "YES"). 

FAB$V«NAM 

Use NAM block inputs; indicates that the NAM block whose address is 
contained in the FAB$L^NAM (name block address) field provides the 
device, file, and/or the directory identification when a file is being opened, 
closed, or erased (deleted). If a file is being created, the field specifies the 
device and directory identification. 

This option has no corresponding FDL attribute and it is not supported for 
DECnet operations. See Chapter 6. 

FAB$V_OFP 

Output file parse; specifies that related file resultant file specification strings, if 
used, are to provide directory, file name, and file type defaults only (requires 
NAM block). 

This option corresponds to the FDL attribute FILE OUTPUT_FILE—PARSE. 

FAB$V_SUP 

Supersede existing file; allows an existing file to be superseded on a Create 
service by a new file of the same name, type, and version. The FAB$V—CIF 
and the FAB$V—MXV option take precedence over the FAB$V—SUP option. 

This option corresponds to the FDL attribute FILE SUPERSEDE. 

File Disposition Options 
FAB$V-DLT 

Delete file on Close; indicates that the file is to be deleted when closed. This 
option may be specified for the Create, Open, or Close services. However, 
if you set the bit when you create or open a file, VMS RMS deletes the file 
when you close it, regardless of the state of the bit when you invoke the 
Close service. You can specify the FAB$V—DLT option with the FAB$V—SCF 
or FAB$V—SPL option. 

This option corresponds to the FDL attribute FILE DELETE—ON—CLOSE. 

FAB$V-SCF 

Submit command file on Close; indicates that the file is to be submitted as a 
batch-command file to the process-default batch queue (SYS$BATCH) when 
the file is closed. This option can be specified for the Create, Open, and Close 
services. However, if you set the bit when you create or open a file, VMS 
RMS submits the file to SYS$BATCH when you close it, regardless of the 
state of the bit when you invoke the Close service. 

The FAB$V—SCF option applies to sequential files only and it corresponds to 
the FDL attribute FILE SUBMIT-ON-CLOSE. 
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FAB$V_SPL 

Spool file on Close; indicates that the file is to be spooled to the process- 
default print queue (SYS$PRINT) when the file is closed. This option can 
be specified for the Create, Open, or Close services. However, if you set the 
bit when you create or open a file, VMS RMS spools the file to SYS$PRINT 
when you close it, regardless of the state of the bit when you invoke the 
Close service. 

The FAB$V_SPL option applies to sequential files only and it corresponds to 
the FDL attribute FILE PRINT_ON_CLOSE. 

FAB$V_TMD 

Temporary file marked for delete; indicates that a temporary file is to be 
created but is to be deleted when the file is closed. This option is input only 
to the Create service. The FAB$V_TMD option takes precedence over the 
FAB$V_TMP option. 

This option corresponds to the FDL attribute FILE TEMPORARY. 

FAB$V_TMP 

Temporary file; indicates that a temporary file is to be created and retained, 
but that no directory entry is to be made for it. This option is used solely as 
input to the Create service. If you have a NAM block, you are given the file 
identification (FID) of the file which you can use to reopen the file. If you 
do not have a NAM block or if you do not save the FID, the file becomes 
inaccessible once it is closed. The FAB$Y_TMD option overrides the FAB$V_ 
TMP option. 

This option corresponds to the FDL attribute FILE DIRECTORY_ENTRY 
("NO" means this bit is set). 

Magnetic Tape Processing Options 
FAB$V-_NEF 

Do not position to end of file; inhibits positioning to the end of a file when 
a tape file is opened and the FAB$B_FAC (file access) field indicates a Put 
service. 

This option corresponds to the FDL attribute FILE MT_NOT_EOF. 

FAB$V«POS 

Current position; directs VMS RMS to position the magnetic tape volume set 
immediately after the most recently closed file when it creates the next file. 

If you use this option when you invoke the $CREATE service, VMS RMS 
overwrites all files located beyond the current tape position. 

The FAB$V_POS option corresponds to the FDL attribute FILE MT_ 
CURRENT-POSITION. The FAB$V_RWO option overrides the FAB$V_ 

POS option. 

FAB$V-RWC 

Rewind file on Close; specifies that the magnetic tape volume is to be 
rewound when the file is closed. This option can be specified for the Close, 
Create, or Open services. 

This option corresponds to the FDL attribute FILE MT—CLOSE—REWIND. 
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FAB$V_RWO 

Rewind on Open; specifies that the magnetic tape volume is to be rewound 
before the file is opened or created. If you use this option when you invoke 
the $CREATE service, VMS RMS overwrites all files currently on the tape 
volume or volume set. The FAB$V_RWO option takes precedence over the 
FAB$V_POS option. 

This option corresponds to the FDL attribute FILE MT_OPEN_REWIND. 

Nonstandard Processing Options 
FAB$V-NFS 

Non-file-structured; indicates (on an Open or Create service) that the volume 
is to be processed in a non-file-structured manner. This option allows the use 
of volumes created on non-DIGITAL systems. 

The FAB$V_NFS option corresponds to the FDL attribute FILE NON_FILE__ 
STRUCTURED and it is not supported for DECnet operations. 

FAB$V_UFO 

User file open; indicates that VMS RMS operations for this file are limited to 
opening it or creating it. To perform additional processing of the file, invoke 
the SYS$QIO system service using the channel number returned by VMS 
RMS in the status value field (FAB$L_STV). This channel is assigned the 
access mode of the caller unless otherwise specified by the FAB$V_CHAN— 
MODE bits. 

If you specify this option, you must set the FAB$B--SHR field FAB$V_UPI 
bit option unless the file is not shared (FAB$B_SHR field FAB$V_-NIL option 
is set). For the Create service, the end-of-file mark is set to the end of the 
block specified in the FAB$L_ALQ field on input. For either the Open or 
Create services, the FAB$W_IFI field is set to 0 on return to indicate that VMS 
RMS cannot perform any more operations on the file. If you set the FAB$V_ 
UFO option with the Open or Create service, the channel needs only to be 
deassigned when you finish with the file. A Close service is not required. 

This option corresponds to the FDL attribute FILE USER_FILE_OPEN and it 
is not supported for DECnet operations. 


5.17 FAB$B_FSZ Field 

The fixed-length control area size (FSZ) field is used only for variable with 
fixed-length control (VFC) records. When you create a file with this record 
type, you must set the value for the fixed-control area before you issue the 
Create service. When you open an existing file that contains variable with 
fixed control records, VMS RMS sets this field equal to the value specified 
when the file was created. The FAB$B JSZ field is not applicable to indexed 
files. 

This field corresponds to the FDL attribute FILE CONTROL _FIELD_SIZE. 

This field contains a numeric value in the range of 1 to 255 that indicates, in 
bytes, the size of the fixed control area; the default size is two bytes. If you 
do not specify a value or specify 0, then the default size is used. 
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5.18 FAB$W_GBC Field 

The global buffer count (GBC) field indicates the requested number of global 
buffers for a file. This field contains a numeric value in the range of 0 to 
32,767; the default is 0. 

Global buffers support sharing of I/O buffers by more than one process. 

The use of global buffers can minimize I/O operations for a shared file, thus 
reducing record access time at the cost of using additional system resources. 
VMS RMS is able to locate requested records (or blocks) in the global buffers 
associated with this file, which it can read directly from memory, eliminating 
much I/O. However, since global buffers use global sections, the value 
contained in FAB$W_GBC is limited by systemwide restrictions on resources 
determined by the system parameters GBLSECTIONS (number of global 
sections), GBLPAGES (number of global page table entries), GBLPAGFIL 
(number of systemwide pages allowed for global page-file sections, or scratch 
global sections), and RMS_GBLBUFQUO (total number of simultaneously 
active VMS RMS global buffers allowed for the system). 

For a complete description of these parameters, see the VMS System Generation 
Utility Manual 

If global buffers are specified for a file, global buffers are used instead of local 
(process) buffers, with the exception of deferred write operations (FAB$L_ 
FOP field FAB$V_DFW option). 

The value that is specified when the file is created is returned in the FAB$W_ 
GBC field as output from the Open service. This value is then used as input 
to the Connect service. 

If you want to override the default value specified when the file was created, 
you can set a different value in the FAB$W_GBC field after opening the file 
but before invoking the Connect service. If you do not want to use global 
buffers, you can clear the field before issuing the Connect service if the 
default value is not 0. 

If you modify the value in the FAB$W_GBC field that is returned from the 
Open service prior to the Connect service, this action determines whether or 
not global buffers are assigned to your process. 

If you want to permanently change the default global buffer count value for 
the file, use the following DCL command: 

$ SET FILE file-spec /GLOBAL_BUFFERS=buffer-count 

If you want to permanently clear the default global buffer count for a file, use 
the following DCL command: 

$ SET FILE file-spec /GL0BAL_BUFFERS=0 

You can also vary the number of global buffers used each time you process 
the file. If you choose this method, you change (or clear) the FAB$VVL.GBC 
field after you open the file, but before you invoke the Connect service. In 
this case, the specified value is assigned to the FAB$W_-GBC field, or the 
FAB$W-_GBC field remains clear only for the current processing of the file; 
that is, you do not permanently alter the FAB$W_GBC field in the FAB. If 
no value is specified in the FAB$W_GBC field when the file is created, the 
default value is 0. 
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The number of global buffers for a file is determined by the first record stream 
to connect to the file (systemwide). If the file is already open and connected, 
then the number of global buffers is already set and modifications made 
before the Connect service are useful only to request that this process use (or 
not use) global buffers. 

To specify a read-only global buffer cache, the initial accessor must set the 
FAB$B_SHR field FAB$V__SHRGET and FAB$V__MSE bits on. Selecting the 
FAB$V_-MSE option turns on locking to coordinate access to the global buffer 
cache. 

You can use global buffers for all file organizations opened for shared record 
access. If the global buffer count is nonzero for the first process that connects 
to the file, then a temporary global section that is large enough to contain the 
specified number of buffers (as well as internal VMS RMS data structures) is 
created and mapped. Subsequent processes that connect to the file map this 
section, thus allowing multiple processes to reference a single set of one or 
more buffers without performing additional I/O operations. Thus, the first 
user to open the file requesting global buffers determines the number of the 
global buffers. 

This field corresponds to the FDL attribute FILE GLOBAL _BUFFER__COUNT 
and it is not supported for DECnet operations. 


5.19 FAB$W_IFI Field 

The internal file identifier (IFI) field is set by VMS RMS to associate the FAB 
with the corresponding internal file access block. VMS RMS sets this field 
on successful Create or Open services. It is then an input for subsequent 
Close, Connect, Display, and Extend services. The Close service deallocates 
the internal control structures and clears the FAB$W_IFI field. When the 
user file open (FAB$V_UFO) option in the FAB$L_FOP field is specified, no 
internal structures are allocated on Create or Open services. Therefore, the 
FAB$W_IFI field remains cleared. 

There is no FDL equivalent for this field. 


5.20 FAB$V_LNM_MODE Subfield 

The logical name translation access mode (LNM^MODE) subfield is the 
component part of the FAB$B_ACMODES field that specifies the outermost 
access mode that VMS RMS uses to translate logical names during parsing. 
The FAB$V.-LNM_MODE subfield contains one of the following values: 

0 None 

1 Executive mode (PSL$C_EXEC) 

2 Supervisor mode (PSL$C_SUPER) 

3 User mode (PSL$C_USER) 

The default value is 0 (none), which VMS RMS interprets as user mode. 

The FAB$V_LNM_MODE field is not supported for DECnet operations, and 
it is ignored during any DECnet remote file access. 

There is no corresponding FDL equivalent for this field. 
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5.21 FAB$L_MRN Field 

The maximum record number (MRN) field applies only to relative files and 
indicates the highest record number that can be written to a file. 

This field contains a numeric value of the highest numbered record allowed 
in the file, in the range of 0 to 2,147,483,647, although the maximum value 
depends on the number of blocks on the device to be used. The default for 
this field is 0. 

If you attempt to write (put) or retrieve (get) a record with a relative record 
number higher than the specified limit, an error occurs and VMS RMS returns 
a message indicating an invalid record number. Checking is suppressed if you 
specify 0 for the FAB$L__MRN field. 

Note that VMS RMS does not maintain the relative record number of the 
highest existing record in the file. 

This field corresponds to the FDL attribute FILE MAX-^RECORD-NUMBER. 


5.22 FAB$W_MRS Field 

The maximum record size (MRS) field defines the size of all records in a file 
with fixed-length records, the maximum size of variable-length records, the 
maximum size of the data area for variable with fixed-length control records, 
and the cell size (minus overhead) for relative files. 

This field contains a numeric value in the range applicable to the file type 
and record format (see Table 5-4) that indicates the size of the records in the 
file, in bytes. This value specifies the number of bytes of data and does not 
include any control bytes associated with each record. 

For fixed-length records, the value represents the actual size of each record 
in the file. You must specify a size when you create a file with fixed-length 
records. 

For variable-length records, the value represents the size of the largest record 
that can be written into the file. If the file is not a relative file, a value of 0 
is used to suppress record size checking, thus indicating that there is no user 
limit on record size, except for the limitations listed in Table 5-4 and certain 
physical limitations. For magnetic tape files, a value of 0 sets an effective 
maximum record size that is equal to the block size minus 4. 

The size of variable-length records must conform to physical limitations. 

With indexed and relative files, for example, records may not cross bucket 
boundaries. If both the FAB$B—BKS and FAB$W—MRS fields are 0 (not 
specified) for an indexed file, VMS RMS attempts to calculate a reasonable 
bucket size, usually 2. Thus, if any record requires more than two buckets, 
you must explicitly specify the required value for the FAB$B—BKS or the 
FAB$W—MRS field. If FAB$B—BKS field is specified, the value should specify 
a bucket size large enough to exceed the longest possible record. 

For variable with fixed-length control records, the value includes only the 
data portion; it does not include the size of the fixed control area. 

For all relative files, the size is used in conjunction with the FAB$B—BKS field 
to determine the size of the record cell. You must specify the FAB$W—MRS 
field when you create a relative file. 
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You specify a value when you invoke a Create service. VMS RMS returns the 
maximum record size when you invoke an Open service. 

Table 5-4 summarizes the maximum record size allowed for the various file 
and record formats. 


Table 5-4 Maximum Record Size for File Organizations and Record 
Formats 


File Organization 

Record Format 

Maximum 

Record Size 

Sequential 

Fixed length 

32,767 

Sequential (disk) 

Variable length 

32,765 

Sequential (disk) 

VFC 

32,767-FSZ' 

Sequential (disk) 

Stream 

32,767 

Sequential (disk) 

Stream-CR 

32,767 

Sequential (disk) 

Stream-LF 

32,767 

Sequential (ANSI Tape) 

Variable length 

9,995 

Sequential (ANSI Tape) 

VFC 

9,995-FSZ’ 

Relative 

Fixed length 

32,255 

Relative 

Variable length 

32,253 

Relative 

VFC 

32,253-FSZ' 

Indexed, Prolog 1 or 2 

Fixed length 

32,234 

Indexed, Prolog 1 or 2 

Variable length 

32,232 

Indexed, Prolog 3 

Fixed length 

32,224 

Indexed, Prolog 3 

Variable length 

32,224 

^The FSZ represents the size, in bytes, of the fixed control area in a record having VFC 
record format. On a disk device, the length of the largest record in a sequential file using 
variable or VFC format is also maintained by VMS RMS and is available through the longest 
record length field (XAB$W_LRL) in the file header characteristics XAB (XABFHC). See 
Chapter 10. 


For DECnet remote file access, the maximum record size may be set by the 
/NETWORK_BLOCK_COUNT=n qualifier to the SET RMS_DEFAULT 
command or by a $XABITM parameter. DECnet remote file access can 
support record sizes as large as the record sizes that VMS RMS supports. The 
default number of blocks is equal to the SYSGEN parameter RMS_DFNBC, 
the default for which is 8 blocks (4096 bytes). For more information about the 
SET RMS—DEFAULT command, see the VMS DCL Dictionary. The SYSGEN 
parameters are detailed in the VMS System Generation Utility Manual. 

This field corresponds to the FDL attribute RECORD SIZE. 
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5.23 FAB$L_NAM Field 

The name block address (NAM) field specifies the address of the NAM 
block used to invoke a file service, such as an Open or Create. The NAM 
block, described in Chapter 6, is required only in conjunction with the file 
specification processing services. But it can also be used with other services, 
typically to obtain a file specification string after all logical name translation 
is completed and all defaults applied. Note that the FAB$L_FOP option 
FAB$V_NAM must be specified for the NAM block to be used as input (see 
FAB$L_FOP). 


5.24 FAB$B_ORG Field 

The file organization (ORG) field assigns the organization of the file. 

The FAB$B_ORG field is a keyword value field in which each file 
organization has a symbolic value. Options are identified using 3-letter 
mnemonics. Each option in the FAB$B_ORG field has its own symbolic 
constant value. For example, the relative (REL) file organization has a 
constant value of FAB$C_REL. 

You must set this field before you invoke a Create service. VMS RMS returns 
the contents of this field when you invoke an Open service. The options are 
described in the following list: 

• FAB$C_1DX — Indexed file organization 

• FAB$C_REL — Relative file organization 

• FAB$C_SEQ — Sequential file organization (default) 

This field corresponds to the FDL attribute FILE ORGANIZATION. 


5.25 FAB$B_RAT Field 

The record attributes (RAT) field indicates the record control information 
associated with each record in a file. 

Within the FAB$B_RAT field, each record attribute has a corresponding bit 
assignment. Each record attribute option in the field has a unique symbolic 
bit offset and constant value. For example, the CR record attribute has a 
symbolic bit offset of FAB$V_CR and a mask value of FAB$M_CR. 

Only the FAB$V_BLK option can be paired with another option. You cannot 
use FAB$V_CR, FAB$V_FTN, and FAB$V_PRN together in any combination. 

For most VMS programs, the default value for this field is FAB$V_CR 
(carriage return). When you create your own file, however, the default 
value is 0. When you want to create a stream format file or any text file 
(a file containing ASCII text), specify the FAB$V_CR option for the Create 
service. VMS RMS sets this field when you invoke an Open service. When a 
process-permanent file is accessed indirectly for output, the value in this field 
is always an input value. VMS RMS automatically converts the records from 
the record attributes specified to the actual attributes of the process-permanent 
file. 

This field corresponds to the FDL primary attribute RECORD. 
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Options 

FAB$V_BLK 

Applicable to sequential files only; indicates that records are not permitted to 
cross block boundaries. 

This option corresponds to the FDL attribute RECORD BLOCK—SPAN. 

FAB$V_CR 

Indicates that each record is to be preceded by a line feed and followed by a 
carriage return when the record is written to a carriage control device such as 
a line printer or terminal. 

This option corresponds to the FDL attribute RECORD CARRIAGE— 
CONTROL CARRIAGE-RETURN. 

FAB$V-FTN 

Indicates that the first byte of each record contains a FORTRAN (ASA) 
carriage control character. 

This option corresponds to the FDL attribute RECORD CARRIAGE— 
CONTROL FORTRAN. Records are defined as follows: 


Byte 0 

Value (hex) 

ASCII 

Character 

Meaning 

0 

(null) 

Null carriage control (sequence: print buffer 
contents). 

20 

(space) 

Single-space carriage control (sequence: line 
feed, print buffer contents, carriage return). 

30 

0 

Double-space carriage control (sequence: line 
feed, line feed, print buffer contents, carriage 
return). 

31 

1 

Page eject carriage control (sequence: form 
feed, print buffer contents, carriage return). 

28 

+ 

Overprint carriage control (sequence: print 
buffer contents, carriage return). Allows 
double printing for emphasis. 

24 

$ 

Prompt carriage control (sequence: line feed, 
print buffer contents). 

Other values 


Same as ASCII space character: single-space 
carriage control. 


FAB$V-PRN 

Indicates print file format for variable with 2-byte fixed-length control records, 
where the fixed control area contains the carriage control specification. The 
first byte of the fixed control area constitutes a "prefix" area, and the second 
byte constitutes a "suffix" area, specifying carriage control to be performed 
before and after printing the record respectively. 
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This option corresponds to the FDL attribute RECORD CARRIAGE- 
CONTROL PRINT. 

The coding scheme of both bytes is presented below (even though they are 
interpreted separately): 


Bit 7 

Bits 6- 

-0 

Meaning 


0 

0 


No carriage control is specified, that is, NULL. 

0 

1-7F 


Bits 6 through 0 are a count of new lines (line feed 
followed by carriage return). 


Bit 7 

Bit 6 

Bit 5 Bits 4-0 

Meaning 

1 

0 

0 

0-1F 

Output the single ASCII control 
character specified by the 
configuration of bits 4 through 0 
(7-bit character set). 

1 

1 

0 

0-lF 

Output the single ASCII control 
character specified by the 
configuration of bits 4 through 0 
that are translated as ASCII characters 
128 through 159 (8-bit character set). 

1 

1 

1 

0-1F 

Reserved. 


5.26 FAB$B_RFM Field 

The record format (RFM) field specifies the format for all the records in a file. 

The FAB$B_RFM field is a keyword value field where each record format has 
a symbolic value. Options are identified by mnemonics. Each option has its 
own symbolic constant value. For example, the FIX (fixed) record format has 
a symbolic constant value of FAB$C_FIX; the STMCR (stream with carriage 
return) record format has a symbolic constant value of FAB$C_STMCR. 

When you create the file, you must set this field before you invoke the Create 
service. VMS RMS returns the record format when you invoke an Open 
service. The record format options are described below. 

This field corresponds to the FDL attribute RECORD FORMAT. 

Options 

FAB$C_FIX 

Indicates fixed-length record format. 

This option corresponds to the FDL attribute RECORD FORMAT FIXED. 

FAB$C_STM 

Indicates stream record format. Records are delimited by FF, VT, LF, or CR 
LF. This format is supported for sequential files only. 

This option corresponds to the FDL attribute RECORD FORMAT STREAM. 


5-25 












File Access Block (FAB) 

5.26 FAB$B_RFM Field 

I 

FAB$C_STMCR 

Indicates stream record format. Records are delimited by CR. This format is 
supported for sequential files only. 

This option corresponds to the FDL attribute RECORD FORMAT STREAM— 
CR. 

FAB$C_STMLF 

Indicates stream record format. Records are delimited by LF. This format is 
supported for sequential files only. 

This option corresponds to the FDL‘attribute RECORD FORMAT STREAM¬ 
ER. 

FAB$C-UDF 

Indicates undefined record format. The undefined record format is valid for 
sequential files only. This is the default value if the FAB is not initialized 
with a $FAB macro. 

This option corresponds to the FDL attribute RECORD FORMAT 
UNDEFINED. 

FAB$C-VAR 

Indicates variable-length record format. For the $FAB macro, this is the 
default value. 

This option corresponds to the FDL attribute RECORD FORMAT VARIABLE. 

FAB$C_VFC 

Indicates variable-length with fixed-length control record format. This format 
is not supported for indexed files. 

This option corresponds to the FDL attribute RECORD FORMAT VFC. 

If you intend to use stream record format, then specify the FAB$V—CR record 
attribute (see FAB$B—RAT). 


5.27 FAB$B_RTV Field 

The retrieval window size (RTV) field specifies the number of retrieval 
pointers VMS RMS is to maintain in memory for the file. Retrieval pointers 
are stored in the file header and indicate the beginning of each extent 
associated with the file. If a file has been extended repeatedly, the extents 
may be scattered noncontiguously on the disk, requiring numerous retrieval 
pointers. When VMS RMS needs to access a new extent, it must first obtain 
the retrieval pointer for that extent. VMS RMS first looks for the retrieval 
pointer in the retrieval window, which contains the number of retrieval 
pointers specified by this field. If the retrieval pointer is not in the retrieval 
window, VMS RMS must first read the file header, causing an additional I/O 
operation. 

This field contains a numeric value in the range of 0 through 127, or 255. A 
value of 0 indicates that VMS RMS is to use the system default number of 
retrieval pointers. A value of 255 means to map the entire file, if possible. If 
you specify a value of 255 when creating a file, the initial number of retrieval 
pointers is minimal; as records are added, however, the number of retrieval 
pointers increases as the number of extents increases. The system resources 
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required for retrieval windows are subtracted from the buffered I/O quota of 
the process. Values from 128 to 254 (inclusive) are reserved for future use. 


This field corresponds to the FDL attribute FILE WINDOW—SIZE and it is not 
supported for DECnet operations. 
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FAB$L_SDC Field 

The secondary device characteristics (SDC) field is equivalent to the 
FAB$L_DEV field, except that secondary device characteristics refer to 
the intermediate device used for spooling or the logical link for DECnet 
operations. Within the FAB$L_SDC field, the bit definitions are the same as 
those defined for the FAB$L_DEV field (see Table 5-2). Like the FAB$L_ 
DEV field, the bit definitions must first be made available to your process 
referring to the $DEVDEF system macro definition; the values are set by 
certain VMS RMS services (see FAB$L_DEV for additional information). 



FAB$B_SHR Field 

The file sharing (SHR) field defines the record operations that the opening 
process allows sharing processes to perform. VMS RMS supports file sharing 
for all file organizations. 

Within the FAB$B_SHR field, each record operation that sharing processes 
are permitted to do has a corresponding bit assignment. You can specify 
multiple record operations (multiple bits may be set). 

Options are identified by symbolic bit offsets. Note that conflicts between the 
names of symbolic offsets in the FAB$B_SHR field and the names of symbolic 
offsets in the FAB$B_FAC field are resolved by prefixing the letters SHR to 
the symbolic offset in the FAB$B_SHR field. For example, both the FAB$B_ 
FAC and FAB$B_SHR fields have a bit that specifies the get record option. In 
the FAB$B_FAC field, this bit offset is assigned the symbol FAB$V_GET; in 
the FAB$B_SHR field, this bit is assigned the symbol FAB$V_SHRGET. 

Note that the letters SHR in the mnemonic part of the bit offset symbol 
may be omitted by VAX MACRO programs. Thus, the GET option, which 

is common to the FAB$B_FAC and FAB$B—SHR fields, has a symbolic • 

bit offset of FAB$V_SHRGET and a mask value of FAB$M_SHRGET, but 
VAX MACRO programs may use the synonyms FAB$V_GET and FAB$M_ 
GET. This rule applies to the FAB$V_SHRPUT, FAB$V_SHRGET, FAB$V_ 
SHRDEL, and FAB$V_SHRUPD options. 

The way in which VMS RMS uses the file access (FAB$B_FAC) field and file 
sharing (FAB$B_SHR) field is described in greater detail in the FAB$B_FAC 
field discussion. 

Note that if you do not specify a value, VMS RMS enters a value of 0 in the 
FAB$B_SHR field. Defaults apply as follows: 

• If the FAB$B_FAC field is set or defaulted to FAB$V_GET, the FAB$B_ 
SHR field defaults to FAB$V_SHRGET. 

• If the FAB$B_FAC field is set or defaulted to either FAB$V_PUT, FAB$V_ 
DEL, FAB$V_UPD, or FAB$V_TRN, the FAB$B_SHR field defaults to 
FAbW—NIL. Thus, write-sharing must be explicitly requested using the 
FAB$B_SHR field (because it is not the default). 
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See the Guide to VMS File Applications for additional details on file sharing. 
This field corresponds to the FDL primary attribute SHARING. 

The following list includes descriptions of the sharing options. 

Options 

FAB$V_MSE 

Allows multistream access and is relevant for record operations only. You 
must specify FAB$V_MSE whenever you want to call Connect services for 
multiple RABs for this FAB. 

Note that if you specify the FAB$V_MSE and FAB$V_BIO options, you must 
set the FAB$\L.UPI bit regardless of the other sharing bits. To specify a read¬ 
only global buffer cache, the initial accessor must set the FAB$B_SHR field 
FAB$V^SHRGET and FAB$V_MSE bits. Selecting the FAB$V-MSE option 
turns on locking to coordinate access to buffers. 

The FAB$V_MSE option is not supported for DECnet operations; an error is 
returned. Although VMS RMS cannot perform multistreaming for DECnet 
operations, you can obtain similar functionality by using multiple FABs to 
access the file in a shared manner. 

This option is available for all file organizations and corresponds to the FDL 
attribute SHARING MULTISTREAM. 

FAB$V_NIL 

Prohibits any file sharing by other users. If FAB$V_NIL is specified with 
other options, it takes precedence. 

This option corresponds to the FDL attribute SHARING PROHIBIT. 

FAB$V__SHRPUT 

Allows other users to write records to the file or to extend the file. 

This option corresponds to the FDL attribute SHARING PUT. 

FAB$V_SHRGET 

Allows other users to read the file. 

This option corresponds to the FDL attribute SHARING GET. 

FAB$V_SHRDEL 

Allows other users to delete records from the file. 

This option corresponds to the FDL attribute SHARING DELETE. 

FAB$V_SHRUPD 

Allows other users to update records that currently exist in the file or extend 
the file. 

This option corresponds to the FDL attribute SHARING UPDATE. 

FAB$V_UPI 

This option is used when the user wants to assume responsibility for 
interlocking of multiple, simultaneous accessors of a VMS RMS file. This 
option disables all VMS RMS locking for the current access of the file. Except 
for block I/O, the FAB$V_MSE option overrides the FAB$V_UPI option. 
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Usually, the FAB$V_-UPI option is used for a file that is open for block I/O 
(FAB$V_BIO or FAB$V_BRO). 

When you select the FAB$V_UFO option, you must also select the FAB$V_ 
UPI option if the file is write shared. A file is specified as being write shared 
when you select either the FAB$Y->PUT option, the FAB$V_DEL option, the 
FAB$V_TRN option or the FAB$V_UPD option in the FAB$B_SHR field. 

This option corresponds to the FDL attribute SHARING USER_INTERLOCK. 


5.30 FAB$L_STS Field 

VMS RMS sets the completion status code (STS) field with success or failure 
codes before it returns control to your program (except for a subset of 
errors, as detailed in Section 2.4). Register 0 contains the same status as 
the STS field. Potential error codes for specific services are listed under their 
descriptions in Part III. Status codes are discussed further in Part I. 


5.31 FAB$L_STV Field 

The status value (STV) field is set by VMS RMS and, on the basis of the 
operation performed and the contents of the completion status code (FAB$L_ 
STS) field, communicates additional completion information to your program. 
See Part III for the instances when VMS RMS uses the status value field. 


5.32 FAB$L_XAB Field 

The extended attribute block address (XAB) field specifies the XAB, or first of 
a series of XABs, that you want to use for file operations. This field contains 
the symbolic address of an XAB control block. A value of 0 (the default) 
indicates no XABs for the file. 

For some operations, you must associate extended attribute blocks (XABs) 
with a FAB to convey additional attributes about a file. (See Part I for a 
description of an XAB.) The FAB$L_XAB field can contain the symbolic 
address of the first associated block (of a potential chained list of such blocks) 
for the file. 

VMS RMS uses XAB values as follows: 

1 If you specify an XAB for either an Open or Display service, VMS RMS 
returns the file attributes to the XAB. 

2 If you specify an XAB for a Create, Close, or Extend service, VMS RMS 
uses the XAB as input to those functions. 


5-29 













0 Name Block (NAM) 


The name (NAM) block provides additional fields for extended file 
specification use, including parsing and obtaining the actual file specification 
used for a file operation. 



6.1 




Summary of Fields 

The symbolic offset, size, and a brief description of each NAM block field are 
presented in Table 6-1. Additional details are given in the remaining sections 
of this chapter. 


Table 6-1 NAM Block Fields 


Field Offset 

Size 

(Bytes) 

Description 

NAM$B_BID’ 

1 

Block Identifier 

NAM$B_BLN’ 

1 

Block length 

NAM$B_DEV2 

1 

Device string length 

nam$l_dev2 

4 

Device string address 

NAM$W_DID2 

6 

Directory identification 

NAM$B_DIR2 

1 

Directory string length 

NAM$L_DIR^ 

4 

Directory string address 

NAM$T_DV|2 

16 

Device Identification 

NAM$L_ESA 

4 

Expanded string area address 

nam$b_esl2 

1 

Expanded string length 

NAM$B_ESS 

1 

Expanded string area size 

nam$w_fid2 

6 

File identification 

nam$l_fnb2 

4 

File name status bits 

nam$b_name2 

1 

File name string length 

NAMSL-NAME^ 

4 

File name string address 

nam$b_node2 

1 

Node name string length 

NAM$L_NODE^ 

4 

Node name string address 

NAM$B_NOP 

1 

Name block options 

NAM$L_RLF 

4 

Related file NAM block address 

NAM$L_RSA 

4 

Resultant string area address 

NAM$B_RSL2 

1 

Resultant string length 

NAM$B_RSS 

1 

Resultant string area size 


^This field is statically initialized by the $NAM macro to identify this control block as a 
NAM. 

^This field cannot be initialized by the $NAM macro. 
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Table 6-1 (Cent.) NAM Block Fields 


Field Offset 

Size 

(Bytes) 

Description 

NAMSB-TYPE^ 

1 

File type string length 

NAM$L_TYPE^ 

4 

File type string address 

NAM$B_VER2 

1 

File version string length 

NAM$L_VER^ 

4 

File version string address 

NAMSL-WCC^ 

4 

Wildcard context 

^This field cannot be initialized by the $NAM macro. 


Each NAM block field is described below. The NAM block fields have no 
corresponding FDL equivalents. However, if your application requires the 
presence of a NAM block, consider using the $NAM macro (or equivalent) 
perhaps in a USEROPEN or a USERACTION routine. 

Unless indicated otherwise, each field is supported for DECnet operations 
when the remote node is a VMS system. Note that the words "DECnet 
operations" in the following descriptions refer to remote file operations 
between two VMS systems. For information about the support of VMS RMS 
options for remote file access to other systems, see the VMS Networking 
Manual. 

Depending on the VMS RMS services to be used, the user may need to 
allocate program storage for the expanded string and the resultant string. 

The Parse service uses the expanded string to pass information related to 
wildcards (or search lists) to the Search service. When it creates a resultant 
string for other VMS RMS file services, VMS RMS uses the expanded string 
as a work area to apply defaults. You can use the resultant string with 
VMS RMS file services to provide the file specification that results from the 
translation of logical names and the application of defaults. Typical uses of 
the resultant string include showing the resulting file specification after a 
partial file specification is entered by a terminal user, for error reporting, and 
for logging the progress of a program. 

To request use of the expanded or resultant strings, you must indicate to VMS 
RMS the address and size of the user-allocated buffer to receive the string. 
The expanded string is indicated by the NAM$L_ESA and NAM$B_ESS 
fields; the resultant string is indicated by the NAM$L_RSA and NAM$B_ 
RSS fields. When it fills in the expanded or resultant strings, VMS RMS 
returns the actual length of the returned string in the NAM$B_ESL or 
NAM$B_RSL fields. 

The format and arguments of the $NAM and $N AM-STORE macros are 
defined in Appendix B. 
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6.2 File Specification Component Descriptors 

For each element of the fully qualified file specification returned in the 
expanded-string field or the resultant-string field in the NAM block, VMS 
RMS returns a descriptor in the NAM block. Two fields describe the element: 
a 1-byte size field and a 4-byte (longword) address field. The fields of these 
descriptors are described as one of the following: 

NAM$B_xxx (size field of xxx) 

NAM$I xxx (address field of xxx) 

Each descriptor is summarized below. 

Descriptor 

NAM$B_NODE, NAM$L_NODE 

Node name descriptor, including access control string and double colon (::) 
delimiter. 

NAM$B_DEV, NAM$L_DEV 

Device name descriptor, including colon (:) delimiter. 

IMAM$B_DIR. NAM$L_DIR 

Directory name descriptor, including brackets ([ and ] or < and > ). 

NAM$B-NAME, NAM$L-NAME 

File name descriptor or, if the file specification following a node name is 
within quotation marks ("file"), a quoted string descriptor. 

NAM$B_TYPE, NAM$L_TYPE 

File type descriptor, including period {.) delimiter. 

NAM$B_VER, NAM$L_VER 

File version number descriptor, including semicolon (;) or period (.) 
delimiter. 

These descriptors are returned, enabling the program to extract a particular 
component from the resultant string without having to parse the resultant 
or expanded string. The entire resultant or expanded string, including 
delimiters, is described by the various component descriptors. If the value in 
the NAM$B_RSL field is nonzero, then the descriptors point to the NAM$L_ 
RSA field. If the value in the NAM$B_RSL field is 0 and the value in the 
NAM$B_ESL field is nonzero, then the descriptors point to the NAM$L_ESA 
field. In all other cases, they are undefined. 
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As an example, a resultant file specification and its file specification 
component descriptors are shown below. 

NODE-'TEST password''::WORK_DISK:[TEST.TEMP]FILE.DAT;3 


NODE 

NODE“TEST password 

DEV 

WORK_DISK: 

DIR 

[TEST.TEMP] 

NAME 

FILE 

TYPE 

.DAT 

VER 

;3 


You can use the field descriptors individually or collectively to describe 
sections of the resultant or expanded string. For example, if you want to use 
the file name and file type fields, use NAM$L_NAME for the starting address 
and NAM$B_NAME+NAM$B_TYPE for the total length. 


6.3 NAM$B_BID Field 

The block identifier (BID) field is a static field that identifies this control block 
as a NAM block. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
NAM$C_BID (this is done by the $NAM macro). 


6.4 NAM$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
NAM block, in bytes. Once set, this field must not be altered unless the 
control block is no longer needed. This field must be initialized to the 
symbolic value NAM$C_BLN (this is done by the $NAM macro). 


6.5 NAM$B_DEV and NAM$L_DEV Fields 

The device name length and address (DEV) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 

NAM$B_RSL fields, which contain the length of the returned file specification 
String. 


6.6 NAM$W_DID Field 

The directory identification (DID) field identifies the directory for the file. 
VMS RMS outputs this 3-word field as part of the Open, Create, Display, and 
Parse services. If, once you open the file, you want to refer to this directory 
again, you can do so more quickly by specifying that the NAM block has a 
valid directory identifier. 

This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 
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6.7 NAM$B_DIR and NAM$L_DIR Fields 

The directory name length and address (DIR) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 


6.8 NAM$T_DVI Field 

The device identification (DVI) field defines the device for the file. VMS RMS 
outputs this field as part of the Open, Create, Display, and Parse services. 
You can use this field with the file identification field to reopen the file by 
referring to the NAM block. The symbolic value NAM$S_DVI gives the 
length of this field in bytes. The form of this field is a counted string. The 
first byte is a count of the number of characters following it. 

This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 


6.9 NAM$L_ESA Field 

The expanded string area address (ESA) field contains the symbolic address of 
a user buffer in the application program to receive the file specification string 
resulting from the translation of logical names and the application of default 
file specification information. 

You must specify this field for processing wildcard characters. 


6.10 NAM$B_ESL Field 

The expanded string length (ESL) field is set by VMS RMS as part of the 
Open, Create, and Parse services. This field contains the length, in bytes, 
of the file specification string returned in the buffer whose address is in the 
NAM$L_ESA field. 


6.11 NAM$B_ESS Field 

The expanded string area size (ESS) field contains the size of the user- 
allocated buffer whose address is contained in the NAM$L_ESA field. 

This field contains a numeric value representing the size, in bytes, of the user 
buffer that will receive the file specification string, in the range of 0 through 
255. 

The symbolic value NAM$C_MAXRSS defines the maximum possible length 
of an expanded file specification string. 
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I 


6.12 NAM$W_FID Field 

The file identification (FID) field is a 3-word field that VMS RMS uses to 
identify the file when it invokes an Open, Create, or Display service. When 
you want to open a file by using the file identifier, set this field before you 
open the file. 

This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 


6.13 NAM$L_FNB Field 

The file name status (FNB) field is a binary options field that VMS RMS 
uses to convey status information obtained from the file specification parsing 
routine. Each bit within this field denotes a specific status relative to the 
various components of the file specification. 

Each status bit has its own offset and mask value. For instance, the number of 
directory levels (DIR_LVLS) field has a symbolic bit offset of NAM$V DIR 

LVLS and a mask value of NAM$M_DIR_LVLS. The bits and the conditions 

they express for the NAM$L_FNB field are described in Table 6-2. 


Table 6-2 NAM$L-FNB Status Bits 


Field Offset 

Description 

NAM$V_CNCL_DEV 

Device name is a concealed device. 

NAM$V_DIR_LVLS 

Indicates the number of subdirectory levels (value is 0 
if there is a user file directory only); a 3-bit field. 

NAM$V_EXP_DEV 

Device name is explicit. 

NAM$V_EXP_DIR 

Directory specification is explicit. 

NAM$V_EXP_NAME 

File name is explicit. 

NAM$V_EXP_TYPE 

File type Is explicit. 

NAM$V_EXP_VER 

Version number is explicit. 

NAM$V_GRP_MBR 

Directory specification is in the group/member number 
format. 

NAM$V_HIGHVER 

A higher-numbered version of the file exists (output 
from Create and Enter services). For DECnet 
operations, this bit is returned as a binary zero. 

NAM$V_LOWVER 

A lower-numbered version of the file exists (output 
from Create and Enter services). For DECnet 
operations, this bit is returned as a binary zero. 

NAM$V_NODE 

File specification includes a node name. 

NAM$V_PPF 

File is indirectly accessed process-permanent file. 

NAM$V_QUOTED 

File specification Includes a quoted string; indicates 
that the file name length and address field contains 
a quoted string file specification. Applies to network 
operations or magnetic tape devices only.^ 
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Table 6-2 (Cent.) NAMSL.FIMB Status Bits 


Field Offset Description 

NAM$V_ROOT_DIR Device name incorporates a root directory. 

NAM$V_SEARCH_LIST A search list logical name is present in the file 

specification. 


NAM$V_WILDCARD File specification string includes a wildcard; returned 

whenever any of the other wildcard bits is set. 


NAM$V_WILD_DIR 

NAM$V_WILD_GRP 

NAM$V_WILD_MBR 

NAM$V_WILD_NAME 

NAM$V_WILD_SFD1- 

NAM$V_WILD_SFD7 

NAM$V_WILD_TYPE 

NAM$V_WILD_UFD 


Directory specification includes a wildcard character. 
Group number contains a wildcard character. 
Member number contains a wildcard character. 

File name contains a wildcard character. 

Subdirectory 1 through 7 specification includes a 
wildcard character. 

File type contains a wildcard character. 

User file directory specification Includes a wildcard 
character. 


NAM$\/_WILD_VER Version number contains a wildcard character. 


NAM$B_NAME and NAM$I—NAME Fields 


The file name length and address (NAME) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 


6.15 NAM$B_NODE and NAM$I—NODE Fields 

The node name length and address (NODE) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
String. 


6.16 NAM$B_NOP Field 

The name block options (NOP) field indicates the options applicable to the 
file name parsing services. 


# 
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The NAM$B_NOP field is a binary options field in which each option has 
a corresponding bit assignment. Multiple options can be specified (multiple 
bits can be set) but the default state for each bit is clear (not set). Each option 
has its own symbolic bit offset and mask value. For example, the SYNCHK 
option has a symbolic bit offset of NAM$V_SYNCHK and a mask value of 
NAM$M-SYNCHK. 

Each of these options is discussed below. 

Options 

NAM$V_NOCONCEAL 

When used with the Open, Create, Search, or Display services, a concealed 
device logical name, if present, is translated into its physical device name (and 
directory, if so defined) in the resultant string field, whose address is supplied 
by the NAM$L_RSA field. If this option is not set and a concealed device 
name is used, the concealed device name appears in the resultant string field, 
instead of the physical device name (and directory, if so defined). 

NAM$V_PWD 

When used with the Create, Open, Parse, Search, or Display services, the 
password in the access control string of a node specification, if present, is 
returned unaltered in the expanded or resultant file specification fields. If 
you do not select this option, the actual password used is replaced by the 
word "password" in the resultant or expanded file specification string fields 
for security reasons. 

NAM$V_SRCHXABS 

When used with the Search service for remote file access, this option directs 
VMS RMS to fill in the FAB and any chained XABs as if a Display service had 
been invoked. This allows you to obtain file attribute information using the 
Search service without the need to open the file. 

NAM$V_SYNCHK 

This gives you the option of using the Parse service to verify the syntax 
validity of the file specification without invoking I/O processing that verifies 
the actual existence of the specified device, directory and file. 

If you invoke the Parse service without setting this bit, an accompanying I/O 
process verifies that the device and directory exist. Note that this processing 
does not verify the existence of the file; you can only verify the existence of 
the file with either a $SEARCH or $OPEN. 

If you opt to set the NAM$V_SYNCHK bit when you invoke the Parse 
service, VMS RMS does not return the device characteristics (FAB$L_DEV 
and FAB$L_SDC fields) and does not fill in the NAM$W_DID and NAM$T_ 
DVI fields, rendering the results of the SPARSE unusable for subsequent 
Search services. 


6.17 NAM$L_RLF Field 

The related file NAM block address (RLF) field contains the symbolic address 
of the NAM block for the related file. This field supports the secondary file 
concept of the command language (DCL), giving an extra default level in 
processing file specifications. 
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To provide an extra level of file specification defaults, the related NAM block 
must have been used previously by an Open, Create, Search or Display 
service to create a resultant file specification string. Moving the address of 
the related NAM block into the NAM$L_RLF field of the current NAM block 
specifies that the previously parsed NAM block's resultant file specification 
string should be used as a default when the current NAM block is parsed. 
Note that the previously parsed NAM block must contain a resultant file 
specification (see NAM$L^RSA and NAM$B__RSS for additional details). 

Refer to the Guide to VMS File Applications for additional details on file 
specification parsing concepts. 


6.18 NAM$L_RSA Field 

The resultant string area address (RSA) field contains the symbolic address 
of a buffer in your program to receive the resultant file specification string. 
The NAM$B_RSS field must also be specified to obtain a resultant file 
specification string. 

This string is the fully specified name of the file that results from the 
resolution of all system defaults, including version numbers and wildcard 
character substitution in the expanded file name string. You must specify this 
field for wildcard processing. 


6.19 NAM$B_RSL Field 

The resultant string length (RSL) contains the length, in bytes, of the 
resultant file specification string returned in the buffer whose address is 
in the NAM$L_RSA field. 


6.20 NAM$B_RSS Field 

The resultant string area size (RSS) field defines the size of the user-allocated 
buffer whose address is contained in the NAM$L_RSA field. 

This field contains a numeric value representing the size, in bytes, of the user 
buffer that will receive the resultant file specification string, in the range of 0 
through 255. 

The symbolic value NAM$C_MAXRSS defines the maximum possible length 
of a resultant file specification string. 


6.21 NAM$B_TYPE and NAM$L_TYPE Fields 

The file type length and address (TYPE) field contains a pointer to either the 
NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse service 
was invoked or an Open, Create, or Search service was invoked. You can tell 
which name string is used by referring to the NAM$B_ESL or NAM$B_RSL 
fields, which contain the length of the returned file specification string. 
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6.22 NAM$B_VER and NAM$L_VER Fields 

The file version length and address (VER) field contains a pointer to either the 
NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse service 
was invoked or an Open, Create, or Search service was invoked. You can 
determine the name string that is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 


6.23 NAM$L_WCC Field 


The wildcard context (WCC) field contains the information needed to use 
wildcard characters in place of the various file specification components. In 
particular, this field restarts a directory search to find the next matching file 
name, type, and/or version number. You can also use it to identify various 
VMS RMS extended contexts; for instance, during remote file processing. 
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7 Record Access Block (RAB) 


The record access block (RAB) defines run-time options for a record stream 
and for individual operations within a predefined record stream context. After 
you connect the file to a record stream and associate the record stream with 
a FAB, you use the RAB fields to specify the next record you want to access 
and to identify appropriate record characteristics. 


Summary of Fields 

Table 7-1 gives the symbolic offset, size, 
description of each RAB field. 

Table 7—1 RAB Fields 

FDL equivalent, and a brief 

Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

RAB$B_BID’ 

1 

None 

Block identifier 

RAB$L_BKT 

4 

CONNECT BUCKET_CODE 

Bucket code 

RAB$B_BLN’ 

1 

None 

Block length 

RAB$L_CTX 

4 

CONNECT CONTEXT 

User context 

RAB$L_FAB 

4 

None 

File access block address 

RAB$W_ISI^ 

2 

None 

Internal stream identifier 

RAB$L_KBF 

4 

None 

Key buffer address 

RAB$B_KRF 

1 

CONNECT KEY_OF_REFERENCE 

Key of reference 

RAB$B_KSZ 

1 

None 

Key size 

RAB$B_MBC 

1 

CONNECT MULTIBLOCK_COUNT 

Multiblock count 

RAB$B_MBF 

1 

CONNECT MULTIBUFFER_COUNT 

Multibuffer count 

RAB$L_PBF 

4 

None 

Prompt buffer address 

RAB$B_PSZ 

1 

None 

Prompt buffer size 

RAB$B_RAC 

1 

CONNECT^ 

Record access mode 

RAB$L_RBF 

4 

None 

Record buffer address 

RAB$W_RFA 

6 

None 

Record file address 

RAB$L_RHB 

4 

None 

Record header buffer 

RAB$L_ROP 

4 

CONNECT^ 

Record-processing options 

RAB$W_RSZ 

2 

None 

Record size 

RABSL-STS^ 

4 

None 

Completion status code 

RAB$L_STV2 

4 

None 

Status value 


^This field is statically initialized by the $RAB macro to identify this control block as a RAB. 

^This field cannot be Initialized by the $RAB macro. 

^This field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 7-1 (Cont.) RAB Fields 


Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

RAB$W_STV0'‘ 

2 

None 

Low-order word status value 

RAB$W_STV2'‘ 

2 

None 

High-order word status value 

RAB$B_TMO 

1 

CONNECT TIMEOUT_PERIOD 

Timeout period 

RAB$L_UBF 

4 

None 

User record buffer address 

RAB$W_USZ 

2 

None 

User record buffer size 

RAB$L_XAB 

4 

None 

Next XAB address 


^Alternate definition of RAB$L_STV field. 


Each RAB field is described below. Unless indicated otherwise, each field is 
supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 

The format and arguments of the $RAB macro and the $RAB_STORE macro 
are described in Appendix B. 


7.2 RAB$B_BID Field 


The block identifier (BID) field is a static field that identifies the block as a 
RAB. Once set, this field must not be altered unless the control block is no 
longer needed. This field must be initialized to the symbolic offset value (this 
is done by the $RAB macro). 


7.3 RAB$L_BKT Field 

The bucket code (BKT) field is used with records in a relative file and when 
performing block I/O. 

This field contains a relative record number or a numeric value representing 
the virtual block number to be accessed. 

For relative files, the relative record number of the record acted upon (or 
which produced an error) is returned to the RAB$L_BKT field only after the 
completion of a sequential operation. That is, VMS RMS returns the relative 
record number when you set the record access mode for sequential access 
(RAB$B_RAC is RAB$C_SEQ) on the execution of a Get, Put, or Find service. 

Before performing block I/O on disk devices, this field must contain the 
virtual block number (VBN) of the first block you want to read or write. 

For all other devices, this field is not used. If you specify a VBN of 0, VMS 
RMS begins the block transfer at the block pointed to by the next block 
pointer (NBP). (The NBP is an internal pointer maintained by VMS RMS; it is 
described in Section 4.8.) 
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7.3 RAB$L_BKT Field 


This field is also input to the Space service to specify the number of blocks to 
be spaced forward or backward. 

This field corresponds to the FDL attribute CONNECT BUCKET—CODE. 


7.4 RAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
RAB, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
RAB$C_BLN (this is done by the $RAB macro). 



7.5 



7.7 


RAB$L_CTX Field 

The user context (CTX) field contains any user-selected value, up to four bytes 
long. This field is devoted exclusively to your use. VMS RMS makes no use 
of the contents of this field; therefore, you can set any value you want in this 
field. For example, you could use this field to communicate with a completion 
routine in your program. 

This field corresponds to the FDL attribute CONNECT CONTEXT. 


RAB$L_FAB Field 

The file access block address (FAB) field contains the symbolic address of the 
FAB for the file. Before you invoke the Connect service, you must set this 
field to indicate the address of the FAB associated with the open file. 


RAB$W-ISI Field 

The internal stream identifier (ISI) field associates the RAB with a 
corresponding FAB. VMS RMS sets this field after the execution of a Connect 
service. A Disconnect service clears this field. This field should not be altered. 


7.8 RAB$L_KBF Field 

The key buffer address (KBF) field contains the symbolic address of the buffer 
containing the key for random access. Note that the RAB$B_KBF field has the 
same offset as the RAB$B_-PBF (prompt buffer address) field, but no conflict 
is presented because the fields are used in mutually exclusive operations. 

You use this field when the RAB$B-_RAC (record access mode) field specifies 
random access by key value and you set it to the address of the buffer that 
contains the key of the desired record. For a relative file (or for a sequential 
disk file with fixed-length records), the key is the relative record number. 

For an indexed file, the key is the key value within the record for the key of 
reference (RAB$B-_KRF). 

# 
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Before you invoke the Get or Find service in random mode to an indexed file, 
you place the address of a location containing a key value in the RAB$L_ 
KBF field. The size of this key value must be specified in the RAB$B__KSZ 
field. During execution of the Get or Find service, VMS RMS uses the key 
value described by the RAB$L_KBF and RAB$B—KSZ fields to search an 
index (which you specify through the contents of the RAB$B_-KRF) and locate 
the desired record in the file. The type of match (that is, exact, generic, 
approximate, or approximate and generic) that VMS RMS attempts between 
the key value you specify and key values in records of the file is determined 
by the RAB$B_KSZ field and the RAB$L_ROP field. 


7.9 RAB$B_KRF Field 

The key of reference (KRF) field specifies the key or index (primary, first 
alternate, and so on) to which the operation applies. The RAB$B--KRF field is 
applicable to indexed files only. 

This field contains a numeric value representing the key path to records in a 
file. The value 0, the default, indicates the primary key. The values 1 through 
254 indicate alternate keys. 

When your program invokes a Get or Find service in random access mode, 
the key of reference specifies the index to search for a match on the key value 
that is described by the RAB$L_-KBF and RAB$B_KSZ fields. When your 
program invokes a Connect or Rewind service, the key of reference identifies 
the index in the file of the next record in the stream. The next record is 
important when records are retrieved sequentially. 

This field corresponds to the FDL attribute CONNECT KEY-_OF_ 
REFERENCE. 


7.10 RAB$B_KSZ Field 

The key size (KSZ) field contains a numeric value equal to the size, in bytes, 
of the record key pointed to by the RAB$L_KBF field. 

Note that the RAB$B_KSZ field has the same offset as the RAB$B_PSZ 
(prompt buffer size) field but no conflict is presented because the fields are 
used in mutually exclusive operations. 

For indexed files, the size of the key depends on the key data type: 

• For string keys, a value from 1 through the size of the key field can be 
used. If the specified size is less than the size of the key field, then only 
the leftmost characters of each key are used for comparison. 

• For numeric key data types, a value of 0 causes VMS RMS to use the key 
data type defined at file creation to determine the key size. A nonzero 
value is checked against the defined size, and an error is returned if they 
are not equal. 

Note that for DECnet operations, the RAB$B-_KSZ field must be explicitly 
specified as a nonzero value because the key data type information may not 
be available to VMS RMS at the local node. 
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The size of the relative record number of a record in a relative file or a 
sequential file with fixed-length records is a longword, positive, integer value; 
therefore, the key size is 4. For relative record numbers, the default value 
of 0 causes a key size of 4 to be used. For DECnet operations, however, the 
RAB$B__KSZ field must be explicitly specified as 4 for relative files. 

With indexed files, the size of key values in bytes of an indexed file can be 
from 1 to 255 bytes. 

A program may access indexed file records directly in one of four ways: 

• By an exact match 

• By an approximate match 

• By a generic match 

• By a combination of approximate and generic matches 

The program specifies the type of match using the RAB$B_KSZ field together 
with two bits from the RAB$L—ROP field: the RAB$V__KGE (logically 
synonymous with RAB$V_EQNXT) bit and the RAB$V_KGT (logically 
synonymous with RAB$V_NXT) bit. 

• To specify an exact match, set a value in the RAB$B_KSZ field equal to 
the number of bytes in the key, and reset the RAB$V_KGE bit and the 
RAB$V_KGT bit. 

• To specify an approximate match, set a value in the RAB$B_KSZ field 
equal to the number of bytes in the key, and set the appropriate bit. 
Specifically, if you want to match on a record having either an equal 
key value or the next value (greater for ascending sort order, lesser for 
descending sort order) set the RAB$V-_-KGE (logically synonymous with 
RAB$V_EQNXT) bit. If you want to match on a record having the next 
value and to ignore equal key values, set the RAB$V_>KGT (logically 
synonymous with RAB$V_NXT) bit. 

Note: Sort order is established in the data type (XAB$B_DTP) field of the 
associated XABKEY when the file is created. 

• To specify a generic match, set a value in the RAB$B—KSZ field equal to 
the number of leading bytes in the key you want to match on, and set the 
RAB$V_KGE bit and the RAB$V_KGT bit. 

• To specify an approximate generic match, set a value in the RAB$B_KSZ 
field equal to the number of leading bytes in the key you want to match 
on, and set the appropriate bit. 


7.11 RAB$B-MBC Field 

The multiblock count (MBC) field applies only to sequential disk file 
operations. This field specifies the number of blocks, in the range of 0 
through 127, to be allocated to each I/O buffer and correspondingly, the 
number of blocks of data to be transferred in each I/O unit. If this field is 
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7.11 RAB$B_MBC Field 


not specified or is specified as 0, the process default for the multiblock count 
is used. If the process default is also 0, VMS RMS uses the system default. 

If the system default is also 0, then the default size for each I/O buffer is 
1 block. The DCL command SET RMS_DEFAULT is used to set process or 
system defaults. 

When it invokes the Connect service, VMS RMS uses the RAB$B_MBC field 
to determine the number of blocks in the I/O transfers for this record stream 
and allocates a buffer with the appropriate storage capacity. Note that the 
RAB$B_MBF (multibuffer count) field may be used to allocate multiple buffers 
of this size for the record stream. 

The use of the RAB$B_MBC field optimizes data throughput for sequential 
operations, and does not affect the structure of the file. It reduces the number 
of disk accesses for record operations, resulting in faster program execution. 
However, the extra buffering increases memory requirements. 

Note that the RAB$B_MBC field is not used with block I/O. With 
multiblocks, the number of blocks in an I/O unit is fixed by the multiblock 
count, whereas in block I/O operations the number of blocks being 
transferred is specified by the program. 

This field corresponds to the FDL attribute CONNECT MULTIBLOCK_ 
COUNT and it is not supported for DECnet operations. 


7.12 RAB$B_MBF Field 

The multibuffer count (MBF) field indicates the number of process-local I/O 
buffers you want VMS RMS to allocate when you invoke the Connect service 
for a record stream. 

This field contains a numeric value in the range of 0 to 127 that represents 
the number of buffers to be allocated. 

If this field is not specified or is set to 0, VMS RMS uses the process default 
for the particular file organization and device type. If the process default is 
also 0, the system default for the particular file organization and device type 
applies. If the system default is likewise 0, one buffer is allocated. However, 
if read-ahead or write-behind is specified, a minimum of two buffers is 
allocated. A minimum of two buffers is also allocated for an indexed file. 

VMS RMS requires that at least one buffer allocated for sequential and relative 
files and at least two buffers for indexed files, unless the file is to be processed 
with block I/O operations only. Multiple buffers can be used efficiently to 
overlap I/O time with compute time, particularly in read-ahead or write- 
behind processing (see RAB$L_ROP for information on these options), and 
to increase use of the buffers (as compared to disk I/O) when performing 
random processing. 

Note that the RAB$B_MBF field is not used when block I/O access is 
specified with the Open, Create, or Connect services because no buffers 
are required. 

This field corresponds to the FDL attribute CONNECT MULTIBUFFER_ 
COUNT and it is not supported for DECnet operations. 


7-6 









Record Access Block (RAB) 

7.13 RAB$L_PBF Field 


7.13 RAB$L_PBF Field 

The prompt buffer address (PBF) field points to a character string to be used 
as a prompt for terminal input. Note that the RAB$B_PBF field has the same 
offset as the RAB$B_KBF (key buffer address) field but because the fields are 
used in mutually exclusive operations, no conflict is presented. 

This field contains the symbolic address of the buffer containing the prompt 
character string. If you select the RAB$V_PMT option of the RAB$L_ROP 
field when you invoke a Get service, VMS RMS outputs this character string 
to the terminal before the Get service begins its task. 

To perform any carriage control on the terminal, you must insert the 
appropriate carriage control characters into this character string. 

This field is not supported for DECnet operations; it is ignored. 


7.14 RAB$B_PSZ Field 

The prompt buffer size (PSZ) field indicates the size of the prompt character 
string to be used as a terminal prompt. This field contains the size, in bytes, 
in the range of 0 to 255. 

Note that the RAB$B_PSZ field has the same offset as the RAB$B-_KSZ (key 
buffer size) field but no conflict is presented because the fields are used in 
mutually exclusive operations. 

This field is not supported for DECnet operations; it is ignored. 


7.15 RAB$B_RAC Field 

The record access mode (RAC) field indicates the method of retrieving or 
inserting records in the file; that is, whether records are read (or written) 
sequentially, directly, or by record file address. Only one access method may 
be specified for any single record operation, but you can change the record 
access mode between record operations. 

The RAB$B_RAC field is a keyword value field in which each record access 
mode has a symbolic offset. (Options are identified using mnemonics. Each 
access mode in the RAB$B_RAC field has its own symbolic constant. For 
example, the SEQ (sequential) access mode has the symbolic constant 
RAB$C_SEQ. 

The RAB$B_RAC field is not applicable to block I/O operations and there is 
no corresponding FDL attribute for this field. 

The record access mode options and their meanings are described below. 

Options 

RABSC^SEQ 

Indicates sequential record access mode (the default); it can be specified with 
any type of file organization. 

Records read from (or written to) sequential files are accessed in chronological 
order. That is, older records are accessed before newer records. 


7-7 









Record Access Block (RAB) 

7.15 RAB$B_RAC Field 



Records read sequentially from indexed files are accessed by the key of 
reference according to the key's sort order. Where records have duplicate 
keys, older records are read before newer records regardless of the key's sort 
order. 

For example, assume an ascending key indexed file with four 2-byte records 
(Al, Bl, B2, Cl) where the key is the first byte of each record. When 
processed sequentially, the records are encountered in the following order: 

Al Bl B2 Cl 

Here records Bl and B2 have the duplicate key B, but record Bl was inserted 
chronologically before record B2 and therefore, is encountered before B2 
when the program is reading records sequentially. 

If this file is reorganized as a descending-key indexed file, the records are 
encountered in the following order: 

Cl Bl B2 Al 

Note that the chronological order of insertion for the two records with 
duplicate keys is maintained without regard to sort order. 

When records are written sequentially to indexed files, VMS RMS verifies that 
the key value of each successive record is ordered correctly with respect to the 
key value in the previously written record. For example, with a descending 
key of reference VMS RMS ensures that the key value of the third record 
written is less than the value of the second record. 

RAB$C-KEY 

Indicates random access by key. For relative files and sequential files on 
disk with fixed-length records, random access is by relative record number. 
Indexed files are accessed directly by specifying the appropriate value for the 
key of reference. 

RAB$C-RFA 

Indicates random access by record file address; used for all disk file 
organizations. 





7.16 RAB$L_RBF Field 


When a program invokes a service that writes records to a file, the output 
record buffer address (RBF) field contains the symbolic address of the buffer 
that holds the record to be written. 

When you invoke the Get or Read service, VMS RMS sets this field to the 
address of the record just read from the file; you need not initialize this field. 


# 
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7.17 RAB$W_RFA Field 

The record file address (RFA) field comprises three words that define the 
physical disk address (not symbolic address) of the current record. 

After the successful execution of a Get, Put, or Find service, VMS RMS sets 
the RAB$W_RFA field to the address of the record acted on by the operation. 
This address provides an unambiguous means of directly locating this same 
record at some later time but is meaningful for disk files only. 

You can store the contents of the RAB$W_RFA field for future use. When 
you want to retrieve the record again, merely restore the saved contents of 
the field, set the record access mode to random by RFA, and invoke a Get or 
Find service. 

The following rules apply to RFA access: 

1 There are two additional names for portions of this field: RAB$L_RFA0 
is the offset of the first of three words; RAB$W_RFA4 is the offset of the 
last word. 

Using VAX MACRO, the field may be copied: 

MOVAL RABBLK.ro 

MOVL RAB$L_RFA0(RO),SAVE.RFA 

MOVW RAB$W_RFA4(RO).SAVE_RFA+4 

2 RFA values remain valid for a record in a sequential file as long as the 
record is within the space defined by the logical file; that is, until the file 
is truncated to a point before the record. 

3 RFA values remain valid for a record in a relative file for the life of the 
file; that is, until the file is reorganized, using the VMS Convert Utility, or 
deleted. 

4 With an indexed file, RFA values remain valid until the file is reorganized, 
using the VMS Convert Utility, or deleted. Note that the VMS Convert 
/Reclaim Utility partially reorganizes a file while maintaining RFA values. 


7.18 RAB$L_RHB Field 

The fixed-length record header buffer (RHB) field contains the symbolic 
address of the record header buffer, which VMS RMS uses only when 
processing VFC records. 

For a Get service, VMS RMS strips the fixed control area portion of the record 
and places it in the buffer whose address is specified in this field. For Put or 
Update services, VMS RMS writes the contents of the specified buffer to the 
file as the fixed control area portion of the record. 

If this field is not specified, VMS RMS assumes the absence of a record 
header buffer. When no record header buffer exists, the fixed control area is 
discarded for a Get service, zeroed for a Put service, and left unchanged for 
an Update service. 

The size of the fixed control area is defined in the FAB, using the FAB$B_>FSZ 
field. You must ensure that the buffer size described in the RAB$L_RHB field 
is equal to the value specified by the FAB$B_FSZ field. 


7-9 








Record Access Block (RAB) 

7.19 RAB$L_ROP Field 


7.19 RAB$L_ROP Field 

RAB$L_ROP is the symbolic offset for the RAB's record-processing options 
(ROP) field. This field specifies which of the various optional record 
operations are to be implemented for the program. 

The ROP is a 32-bit field in which each record-processing option has a 
corresponding bit assignment to let you specify multiple options (multiple 
bits can be set), when applicable. Each option has a unique symbolic offset 
and a unique mask value but you need only specify the appropriate 3-letter 
mnemonic when coding a function. For example, the end-of-file option is 
assigned symbolic offset RAB$Y_EOF, but to specify the option, you use the 
following MACRO statement: 

R0P=E0F 

The record-processing option bits are never affected by VMS RMS services. 

This section describes the record-processing options alphabetically by 
functional category, of which there are seven: 

• Connect service input options 

• Indexed file options 

• Miscellaneous options 

• Performance options 

• Put service options 

• Record locking options 

• Terminal device options 

This field corresponds to the FDL primary attribute CONNECT. 

Table 7-2 lists the options alphabetically by category. 


Table 7-2 Record Processing Options 


Option 

Symbolic Offset 

Connect Service Options 

Block I/O 

RAB$V_BIO 

End of file 

RAB$V_EOF 

Read ahead 

RAB$V_RAH 

Synchronous status 

RAB$V_SYSCSTS 

Write behind 

RAB$V_WBH 

Indexed File Options 

Key greater than or equal 

RAB$V_EQNXT (or RAB$V_KGE) 

Limit 

RAB$V_LIM 

Load 

RAB$V_LOA 

Key greater than 

RAB$V_NXT or (RAB$V_KGT) 
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Table 7~2 (Cent.) Record Processing Options 
Option Symbolic Offset 

Miscellaneous Option 

Timeout RAB$V_TMO 


Performance Options 


Asynchronous 

RAB$V_ASY 

Fast delete 

RAB$V_FDL 

Locate mode 

RAB$V_LOC 

Read ahead 

RAB$V_RAH 

Write behind 

RAB$V_WBH 

Put Service Options 

Truncate on put 

RAB$V_TPT 

Update-if 

RAB$V_UIF 


Record Locking Options 


Do not lock 

RAB$V_NLK 

Nonexistent record 

RAB$V_NXR 

Lock for read 

RAB$V_REA 

Lock for write 

RAB$V_RLK 

Ignore read lock 

RAB$V_RRL 

Timeout 

RAB$V_TMO 

Manual unlock 

RAB$V_ULK 

Wait to lock 

RAB$V_WAT 

Terminal Device Options 


Cancel CTRL/0 

RAB$V_CCO 

Convert 

RAB$V_CVT 

Extended operation 

RAB$V_ETO 

Prompt 

RAB$V_PMT 

Purge type-ahead 

RAB$V_PTA 

Read, no echo 

RAB$V_RNE 

Read, no filter 

RAB$V_RNF 

Timeout 

RAB$V_TMO 

In the following text, each of the options is described under its symbolic 
offset. For example, the asynchronous option is described under RAB$V_ 
ASY. 
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Connect Service Options 
RAB$V_BIO 

Block I/O; specifies that only block I/O operations are to occur, when mixed 
record I/O and block I/O operations are allowed. This option is meaningful 
only if the FAB$B_FAC FAB$V_BRO option was specified when the file was 
opened (by a Create or Open service). When the RAB$V_BIO option is set 
for the Connect service, only block I/O operations are allowed for this record 
stream. When the RAB$V__BIO option is clear for the Connect service, only 
record I/O operations are allowed when accessing a relative or indexed file 
and mixed (block I/O and record I/O) operations are allowed for sequential 
files. This option corresponds to the FDL attribute CONNECT BLOCK—lO. 

RAB$V-EOF 

End-of-file; indicates that VMS RMS is to position the record stream to the 
end of the file for the connect record operation only. 

This option corresponds to the FDL attribute CONNECT END_OF_FILE. 

RAB$V__RAH, RAB$V-WBH 

Read ahead and write behind; see explanation under "Performance Options". 

Note that the first three indexed file options have limited application with 
relative files. See the Guide to VMS File Applications for details. 

The indexed file options may be enabled or disabled during any record 
operation. 

As shown in the following chart, synonyms have been defined for the two 
key search options, RAB$V__KGT and RAB$V_KGE, to reflect the functional 
capability for processing records in ascending or descending order. DIGITAL 
recommends you use these synonyms when coding new applications. 


Search Option 

Synonym 

Definition 

RAB$V_KGE 

RAB$V_EQNXT 

Return the record with an equal key 
value, or the next key value according 
to the sort order for the current key of 
reference. 

RAB$V_KGT 

RAB$V_NXT 

Return the record with the next key 
value according to the sort order for the 
current key of reference. 


Indexed File Options 
RAB$V_EQNXT 

The symbolic offset RAB$V_EQNXT is logically synonymous with the 
symbolic offset RAB$V_KGE. When you select this option and ascending 
sort order is specified, VMS RMS returns the next record having a key value 
equal to or greater than the value specified by the RAB$L—KBF and RAB$B— 
KSZ fields. If descending sort order is specified, VMS RMS returns the next 
record that contains a key value equal to or less than the value specified by 
the RAB$L_KBF and RAB$B_KSZ fields. 
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Note: Sort order is established in the data type field (symbolic offset XAB$B- 
DTP) of the associated XABKEY when the file is created. 

If the program specifies a RAB$V_EQNXT search and no record has a key 
value identical to the specified search value, VMS RMS returns the record 
with the next key value according to the specified sort order. (See the 
description of the RAB$V_NXT bit.) 

If the program specifies a RAB$V_EQNXT search and a record with a key 
value identical to the search key is found, VMS RMS returns the record 
regardless of sort order. 

For example, consider an ascending-key indexed file having three records. A, 
B, and C, where the key for each record is the record itself. When the file is 
processed sequentially, the records are encountered in the following order: 

ABC 

If the program does a RAB$V__EQNXT search specifying the B key value, 
VMS RMS returns record B. 

If this file is reorganized as descending-key indexed file and it is processed 
sequentially, the records are encountered in the following order: 

C B A 

Again, when the program does a RAB$V—EQNXT search specifying the B key 
value, VMS RMS returns record B. 

If neither a RAB$V_EQNXT search nor a RAB$V_NXT search (logically 
synonymous with RAB$V_KGT) is specified, an exact key match is required 
unless a generic key match is specified. (See the description of the RAB$B_ 
KSZ bit.) 

This option corresponds to the FDL CONNECT attribute KEY-GREATER_ 
EQUAL. 

RABSV^KGE 

This option is logically synonymous with the RAB$V__EQNXT option and is 
described under RAB$V_EQNXT. 

RAB$V_KGT 

This bit is logically synonymous with the RAB$V_NXT option and is 
described under RAB$V_NXT. 

RAB$V_LIM 

This option is supported for indexed files only. It permits you to use VMS 
RMS as a limit sensor when accessing a file sequentially. When the RAB$V-_ 
LIM bit is set, the key value defined by the RAB$L^KBF and RAB$B_KSZ 
fields (limit key value) is compared to the key value in each record as it is 
accessed. When a record is accessed that has a key value different from the 
limit key value, VMS RMS returns the RMS$—OK_LIM success status code. 

This option corresponds to the FDL attribute CONNECT KEY_LIMIT. 

RAB$V-LOA 

This option is supported for indexed files only. It specifies that VMS RMS is 
to load buckets according to the fill size established when the file is created. 
The bucket fill size is established in the XAB$W_DFL and XAB$W_-IFL fields 
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of the key definition XAB. If LOA is not specified, VMS RMS ignores the 
established bucket fill size; that is, buckets are completely filled. 

This option corresponds to the FDL attribute CONNECT FILL__BUCKETS. 

RAB$V_NXT 

The symbolic offset (RAB$V-_NXT) is logically synonymous with the symbolic 
offset RAB$V_KGT. When the bit is set and ascending sort order is specified, 
VMS RMS returns the next record having a key value greater than the value 
specified by the RAB$L__KBF and RAB$B__KSZ fields. If descending sort 
order is specified, VMS RMS returns the next record having a key value 
less than the value specified by the RAB$L_KBF and RAB$B—KSZ fields. 

If neither RAB$V_-KGT nor RAB$V__EQNXT (logically synonymous with 
RAB$V_-KGE) is specified, an exact key match is required. 

Note: Sort order is established in the data type XAB$B_DTP field of the 
associated XABKEY when the file is created. 

The key searching usually produces different results depending on the 
specified sort order. For example, consider an ascending-key indexed file 
having three records. A, B, and C, where the key for each record is the record 
itself. When the file is processed sequentially, VMS RMS returns the records 
in the following order: 

ABC 

If the program does a RAB$V_KGT search specifying the B key value, VMS 
RMS returns record C. 

If this file is reorganized as descending-key indexed file and is processed 
sequentially, the records are returned in the following order: 

C B A 

Now when the program does a RAB$V_KGT search specifying the B key 
value, VMS RMS returns record A. 

This option corresponds to the FDL CONNECT attribute KEY__GREATER__ 
THAN. 

Miscellaneous Options 
RAB$V_TMO 

Timeout; in addition to its use for terminals and preventing delays due 
to record locks (described later), the RAB$V_TMO option serves a special 
purpose for mailbox devices. If specified in combination with a timeout value 
of 0 (RAB$B_TMO), Get and Put services to mailbox devices use the IO$M_ 
NOW modifier. Doing so causes the operation to complete immediately, 
instead of synchronizing with another cooperating writer or reader of the 
mailbox. 

This option corresponds to the FDL attribute CONNECT TIMEOUT__ENABLE 
and is not supported for DECnet operations. 

See the VMS I/O User's Reference Volume for a further discussion of 
mailboxes. 
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Performance Options 
RAB$V_ASY 

Asynchronous; indicates that this I/O operation is to be performed 
asynchronously. When you specify RAB$\Lj\SY, you pass the address of 
the RAB as an argument to the AST routine. VMS RMS returns control to 
your program as soon as an I/O operation is initiated, even though that 
operation may not yet be completed. This option is normally used with 
a Wait service to synchronize with operation completion; it is ignored for 
process-permanent files. 

The RAB$V_ASY option corresponds to the FDL attribute CONNECT 
ASYNCHRONOUS. 

RAB$V_FDL 

Fast delete; this option reduces the time required to delete records in indexed 
files. The saving in time is achieved by temporarily avoiding the processing 
needed to eliminate pointers from alternative indexes to the record. However, 
there is a cost associated with this option. First, the structural linkage from 
the alternate indexes remains in place but has no utility; therefore, a certain 
amount of space is wasted. Second, if the program tries to access the deleted 
record from an alternate index, VMS RMS traverses the linkage, finds the 
record no longer exists and then generates a "nonexistent record" error 
message which the program must process. 

You should take the fast delete option only if the immediate saving in time is 
of greater benefit to you than the associated costs in space and overhead. 

This option corresponds to the FDL attribute CONNECT FAST__DELETE. 

RAB$V_LOC 

Locate mode; under specified conditions, you have the option of specifying 
locate mode instead of move mode, the default method of buffer handling. 

In locate mode, your program accesses records directly in an I/O buffer. 
Thus, VMS RMS does not have to move records between I/O buffers and an 
application program buffer. The RAB$V_LOC option activates locate mode. 
VMS RMS supports this option for the Get service only. The conditions that 
may prohibit the use of the locate mode option are given in the following list: 

• Record crosses block boundaries. 

• The FAB$B_FAC field FAB$V_UPD option is set. 

• There are multiple record streams. 

• Process-permanent files are accessed indirectly. 

• Records are compressed in indexed Prolog 3 files. 

In move mode, VMS RMS transfers individual records between I/O buffers 
and your program buffer. When you invoke a Get service, VMS RMS reads 
a block or set of blocks (for sequential files) or a bucket (for relative and 
indexed files) into an I/O buffer. VMS RMS then selects the desired record 
from the buffer and moves it into the program-specified location. Locate 
mode eliminates the last step. 

This option corresponds to the FDL attribute CONNECT LOCATE _MODE 
and it is not supported for DECnet operations; move mode is always used. 
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RAB$V_RAH 

Read-ahead; used with multiple buffers (see RAB$B__MBF) to indicate read- 
ahead operations. VMS RMS issues I/O requests as soon as possible when 
a buffer is needed. When the first buffer is filled, the I/O operation takes 
place for the first buffer as the second buffer receives the next record; the 
second buffer soon becomes filled and the next record is read into the first 
buffer as the I/O operation for the second buffer occurs. The system does 
not have to wait for I/O completion, which permits an overlapping of input 
and computing. Read-ahead is ignored for unit record device I/O and is 
supported only for the nonshared sequential file organization. If the RAB$V_ 
RAH option is specified when the multibuffer count (RAB$B^MBF) is 0, 
two buffers are allocated to allow multibuffering. If two or more buffers are 
specified, multibuffering is allowed regardless of what was specified to the 
Connect service. Conversely, if a buffer count of 1 is specified, multibuffering 
is disabled regardless of what was specified to the Connect service. 

This option corresponds to the FDL attribute CONNECT READ-AHEAD and 
it is not supported for DECnet operations. 

RAB$V_SYNCSTS 

When you select this option, VMS RMS returns the success status RMS$— 
SYNCH if the requested service completes its task immediately. The most 
common reason for not completing a task immediately is that the task 
involves I/O operations. 

The status RMS$—SYNCH is returned in RO only. Refer to the RAB$L—STS 
field for the actual success status or failure status of the task. 

The RAB$V—SYNCSTS option should be used in conjunction with the 
RAB$V—ASY option. 

RAB$V-WBH 

Write-behind; used with multiple buffers (see RAB$B—MBF). When one 
buffer is filled, the next record is written into the next buffer while the 
I/O operation takes place for the first buffer. The system does not have 
to wait for I/O completion, which allows for an overlapping of computing 
and output. Write-behind is ignored for unit record devices. This option 
is implemented only for the nonshared sequential file organization. If the 
RAB$V—WBH option is specified when the multibuffer count (RAB$B—MBF) 
is 0, two buffers are allocated to allow multibuffering. If two or more buffers 
are specified, multibuffering is allowed regardless of what was specified to the 
Connect service. Conversely, if a buffer count of 1 is specified, multibuffering 
is disabled regardless of what was specified to the Connect service. 

This option corresponds to the FDL attribute CONNECT WRITE-BEHIND 
and it is not supported for DECnet operations. 

Put Service Options 
RAB$V-TPT 

Truncate-on-put; specifies that a Put or Write service using sequential record 
access mode can occur at any point in the file, truncating the file at that point. 
The end-of-file mark is set to the position immediately following the last byte 
written. 
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Truncating a file deletes all records beyond the point of truncation. In a 
shared environment, the application must ensure proper interpretation of a 
truncate operation. The process must have specified truncate access by setting 
the FAB$V_TRN option in the FAB$B_FAC field when the file was opened or 
created. 

This option applies only to sequential files and corresponds to the FDL 
attribute CONNECT TRUNCATE_ON_PUT. 

RAB$V_UIF 

Update-if; indicates that if a Put service is invoked for a record that already 
exists in the file, the operation is converted to an Update. This option is 
necessary to overwrite (as opposed to update) an existing record in relative 
and indexed files. Indexed files using this option must not allow duplicates 
on the primary key. The process must have specified Update access by setting 
the FAB$V_UPD option in the FAB$B_FAC field when the file was opened or 
created. 

When using this option with shared files and automatic record locking, you 
should be aware that the Put service, unlike the Update service, briefly 
releases record locks until it is determined that an Update should take 
place. At that point, the record is relocked for the Update operation. Note 
that during the time the Put operation is being converted into an Update 
operation, it is possible that another record stream could update or delete the 
record. 

This option corresponds to the FDL attribute CONNECT UPDATE _IF. 

The record-processing options related to controlling record locking are 
described below. Except as noted, these options apply to all file organizations 
and may be selected for each operation. 

Record Locking Options 
RAB$V_NLK 

Do not lock record; specifies that the record accessed through a Get or Find 
service is not to be locked. The RAB$V_NLK option takes precedence over 
the RAB$V_ULK option. 

This option corresponds to the FDL attribute CONNECT NOLOCK. 

RAB$V_IMXR 

Nonexistent record processing; specifies that if the record directly accessed 
through a Get or Find service does not exist (was never inserted into the file 
or was deleted), the service is to be performed anyway. For a Get service, 
the previous contents of a deleted record are returned. The processing of a 
deleted record returns a completion status code of RMS$_OK_DEL, and the 
processing of a record that never existed returns RMS$_OK_RNF. 

This option applies only to relative files and it corresponds to the FDL 
attribute CONNECT NONEXlSTENT_RECORD. 

RAB$V_REA 

Lock record for read; specifies that the record is to be locked for a read 
operation for this process, while allowing other accessors to read the record 
(but not to modify the record). Use this option only when you do not want 
the file to be modified by any subsequent activities. Use the RAB$V_RLK 
option to allow possible subsequent modification of the file. 

This option corresponds to the FDL attribute CONNECT LOCK_ON_READ. 
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RAB$V_RLK 

Lock record for write; specifies that a user who locks a record for modification 
is allowing the locked record to be read by other accessors. If both RAB$V_ 
RLK and RAB$V_REA option are specified, the RAB$V_REA option is 
ignored. The RAB$V_NLK option takes precedence over all others. 

This option corresponds to the FDL attribute CONNECT LOCK—ON_ 
WRITE. 

RAB$V_RRL 

Read regardless of lock; read the record even if another stream has locked the 
record. This option allows the reader some control over access. If a record 
is locked against all access and this bit is set for either a Put or Get service 
request, the record is returned with alternate status RMS$—OK—RRL. 

This option corresponds to the FDL attribute CONNECT READ- 
REGARDLESS. 

RAB$V-TMO 

Timeout; specifies that if the RAB$V—WAT option was specified, the RAB$B— 
TMO field contains the maximum time value, in seconds, to be allowed for 
a record input wait caused by a locked record. If the timeout period expires 
and the record is still locked, VMS RMS aborts the record operation with the 
RMS$—TMO completion status. Note that the maximum time allowed for a 
timeout is 255 seconds. Other functions of the RAB$V—TMO option are listed 
under "Miscellaneous Options." 

This option corresponds to the FDL attribute CONNECT TIMEOUT—ENABLE 
and it is not supported for DECnet operations. 

RAB$V-ULK 

Manual unlocking; prohibits VMS RMS from automatically unlocking records. 
Instead, once locked (through a Get, Find, or Put service), a record must be 
specifically unlocked by a Free or Release service. The RAB$V—NLK option 
(above) takes precedence over the RAB$V—ULK option. 

This option corresponds to the FDL attribute CONNECT MANUAL — 
UNLOCKING. 

RAB$V-WAT 

Wait; if the record is currently locked by another stream, wait until it is 
available. This option may be used with the RAB$V—TMO option (see above) 
to limit waiting periods to a specified time interval. 

This option corresponds to the FDL attribute CONNECT WAIT—FOR— 
RECORD. 

The record-processing options related to terminal devices are described 
below. These options map directly into equivalent modifiers to the QIO 
function code. For a further discussion of their effects, see the VMS I/O 
User's Reference Volume. These options can be selected for each operation. 
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Terminal Device Options 
RAB$V_CCO 

Cancel CTRL/O; guarantees that terminal output is not discarded if the 
operator presses CTRL/O. 

This option corresponds to the FDL attribute CONNECT TT_CANCEL_ 
CONTROL _0 and it is not supported for DECnet operations. 

RAB$V_CVT 

Convert; changes characters to uppercase on a read from a terminal. 

This option corresponds to the FDL attribute CONNECT TT_-.UPCASE-_ 
INPUT and it is not supported for DECnet operations. 

RAB$V_ETO 

Extended terminal operation; indicates presence of a Terminal XAB (XABTRM) 
to describe terminal input using extended terminal characteristics. Note that 
if this option is specified, all other RAB$L_ROP options specific to terminal 
devices are ignored (including the RAB$\L.TMO option). 

This option is not supported for DECnet operations. 

RAB$V^PMT 

Prompt option; indicates that the contents of the prompt buffer are to be used 
as a prompt for reading data from a terminal (see RAB$L_PBF field). 

This option corresponds to the FDL attribute CONNECT TT_PROMPT and it 
is not supported for DECnet operations. 

RAB$V_PTA 

Purge type-ahead; eliminates any information that may be in the type-ahead 
buffer on a read from a terminal. 

This option corresponds to the FDL attribute CONNECT TT_PURGE_TYPE_ 
AHEAD and it is not supported for DECnet operations. 

RAB$V_RNE 

Read no echo; indicates that input data is not echoed (displayed) on the 
terminal as it is entered on the keyboard. 

This option corresponds to the FDL attribute CONNECT TT_READ_ 
NOECHO and it is not supported for DECnet operations. 

RAB$V_RNF 

Read no filter; indicates that CTRL/U, CTRL/R, and DELETE are not to be 
considered control commands on terminal input but are to be passed to the 
application program. 

This option corresponds to the FDL attribute CONNECT TT_READ_ 
NOFILTER and it is not supported for DECnet operations. 

RAB$V_TMO 

Timeout; for terminal operations, indicates that the content of the RAB$B__ 
TMO field is to be used to determine the number of seconds allowed between 
characters received during terminal input. If the timeout period expires, 

VMS RMS returns an error status (see RAB$B_TMO). Other functions of the 
RAB$V_TMO option are listed under "Miscellaneous Options" and "Record 
Locking Options". 
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This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE 
and is not supported for DECnet operations. 


7.20 RAB$W_RSZ Field 

The record size (RSZ) field contains the size, in bytes, of the record. For a 
Write service, the range is 1 through 65,535. For a Put or Update service, the 
range is 0 to the maximum value shown in Table 5-4. This field controls the 
size of a record that a Put or Update service can write, or the number of bytes 
that a Write (block I/O) service can write. This field is required for an Update 
service only if the file contains variable-length records or VFC records. 

On input from a file, VMS RMS sets this field to indicate the length, in bytes, 
of the record that a Get service transfers or that a Read service (block I/O) 
reads. 

Three notes apply to this field: 

1 After a Get service, VMS RMS places the record size in the RAB$W-_RSZ 
field. On a Read service, VMS RMS sets the RAB$W-_RSZ field to the 
number of bytes actually transferred. 

2 For variable with fixed-length control records, VMS RMS does not include 
the size of the fixed control area in the RAB$W_RSZ field. 

3 For block I/O operations, some devices require that an even number of 
bytes be transferred. 


7.21 RAB$L_STS Field 

The completion status code (STS) field is set by VMS RMS with the success 
or failure status codes for a record operation before returning control to your 
program. For an asynchronous operation that has been initiated but not 
yet completed, this field is 0. When the operation is complete, the field is 
updated with the completion status. See Part I for additional details about 
signaling VMS RMS status codes. Potential error codes for specific operations 
are listed with their descriptions in Part III. 


7.22 RAB$L_STV Field 

The completion status value (STV) field communicates additional completion 
information to your program, on the basis of the type of operation and the 
contents of the completion status code field. For additional information on 
the RAB$L--.STS and RAB$L_STV fields, see Part I. 

The RAB$L^STV field can be accessed using alternate symbolic offsets; 
RAB$W_STV0 is the location of the first word and RAB$W_STV2 is the 
location of the second word within RAB$L_STV. 
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7.23 RAB$B_TMO Field 

The timeout (TMO) field indicates the maximum number of seconds, in the 
range 0 to 255, that VMS RMS should wait for an operation to conclude. If 
the operation does not conclude within the specified timeout period, VMS 
RMS returns an error status code. 

To use this field, you must also specify the RAB$V_TMO record-processing 
option. 

For a Get service using a terminal device, this value specifies the number 
of seconds to wait between the characters being typed. If you specify 0 
along with RAB$V-_TMO, the current contents of the type-ahead buffer are 
returned. 

When you use a wait-on-record lock (RAB$V_WAT) with a Get, Find, or Put 
service, this value specifies the maximum number of seconds for VMS RMS 
to wait for the record to become available. 

Note that if the RAB$B_TMO field contains a value of 0 and RAB$V_TMO 
is set when you invoke either a Get or Put service to a mailbox device, the 
operation terminates immediately, rather than waiting for another process. 
For example, if you invoke the Put service to a mailbox device with the 
RAB$B_TMO field clear, the Put service does not wait for the receiving 
process to get the record. 

This field corresponds to the FDL attribute CONNECT TIMEOUT_PERIOD 
and it is not supported for DECnet operations. 


7.24 RAB$L_UBF Field 

The user record buffer address (UBF) field indicates the location of a record or 
block buffer. 

Note: When you invoke the GET service, RMS takes control of the record buffer 
and may modify it. RMS returns the record size and only guarantees the 
contents from where it accessed the record to the completion of the record. 

This field contains the symbolic address of a work area (buffer) within your 
program. The size of this buffer must be defined in the RAB$W_USZ (user 
record area size) field. 

When you invoke a Get service, this field must contain the buffer address, 
regardless of the record transfer mode (locate or move). This option also 
applies when you invoke the Read service for block I/O. However, a Put or 
Write service never needs a user buffer. 


7.25 RAB$W_USZ Field 

The user record buffer size (USZ) field indicates the length, in bytes, of the 
user record or block buffer. This field contains a numeric value representing 
the size of the buffer, in the range of 1 through 65,535. 

The user record buffer should be large enough to contain the largest record in 
the file. If the buffer is not large enough on an operation with a Get service, 
VAX RMS moves as much of the record as possible into the buffer and returns 
a warning status code. 
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The value in this field specifies the transfer length, in bytes, for block I/O 
operations with a Read service and for a Get service to UDF (undefined) 
format sequential files. 


7.26 RAB$L_XAB Field 

The extended attribute block address (XAB) field contains the symbolic 
address of an XAB control block that you want to use when performing 
an operation such as a Get service for a terminal device. A value of 0 (the 
default) indicates no XABs for this record stream. 

For certain record operations, you can associate XABs with a RAB to convey 
additional attributes about an operation. (See Part 1 for the description of an 
XAB.) 
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Allocation Control XAB (XABALL) 


The allocation control XAB (XABALL) provides additional control over file or 
area space allocation on disk devices in order to optimize performance. In the 
following descriptions, the terms file and area are synonymous for sequential 
and relative files because these file organizations are limited to a single area 
(Area 0). 


8.1 Summary of Fields 

When VMS RMS uses a XAB to create or extend an area, the following 
XABALL fields duplicate and take precedence over associated fields in the 
related FAB: 

• Allocation quantity (ALQ) field, XAB$L_ALQ, overrides FAB$L__ALQ 

• Bucket size (BKZ) field, XAB$B_BKZ, overrides FAB$B_BKS 

• Default extension quantity (DEQ) field, XAB$W-_DEQ, overrides FAB$W_- 
DEQ 

• The XAB$V_CBT and XAB$V_CTG options of the allocation options field, 
XAB$B_AOP, override the FAB$V_-CBT and FAB$V^CTG options of the 
file-processing options field, FAB$L_FOP 

When opening a file or displaying a file's attributes, VMS RMS outputs 
appropriate information to your program using these fields. 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABALL field are presented in Table 8-1. 


Table 8-1 XABALL Fields 


Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

XAB$B_AID 

1 

AREA n 

Area identification number 

XAB$B_ALN 

1 

AREA POSITION^ 

Alignment boundary type 

XAB$L_ALQ 

4 

AREA ALLOCATION 

Allocation quantity 

XAB$B_AOP 

1 

AREA^ 

Allocation options 

XAB$B_BKZ 

1 

AREA BUCKET_SIZE 

Bucket size 

XAB$B_BLN2 

1 

None 

Block length 

XAB$B_C0D2 

1 

None 

Type code 

XAB$W_DEQ 

2 

AREA EXTENSION 

Default extension quantity 

XAB$L_LOC 

4 

AREA POSITION 

Location 

XAB$L_NXT 

4 

None 

Next XAB address 


^This field contains options; corresponding FDL equivalents are listed in the description of the field. 


^This field is statically initialized by the $XABALL macro to identify this control block as a XABALL. 
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Table 8-1 (Cont.) XABALL Fields 


Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

XAB$W_RFI 

6 

AREA POSITION FILE.ID 
or FILE_NAI\/IE 

Related file identifier 

XAB$W_VOL 

2 

AREA VOLUME 

Related volume number 


Each XABALL field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 

The format and arguments of the $XABALL macro and the $XABALL_ 
STORE macro are described in Appendix B. 


8.2 XAB$B_AiD Fields 

VMS RMS uses the area identification number (AID) field to determine which 
area within a file is supported by this XAB. Note that sequential and relative 
files are limited to area 0. 

The area is identified by a numeric value in the range 0 through 254 (default 
is 0) and is most appropriate for use with index files having multiple areas 
allocated. 

This field corresponds to the FDL attribute AREA n where n indicates the area 
number. 


8.3 XAB$B_ALN Field 

The alignment boundary type (ALN) field gives you several options for 
aligning the allocated area. VMS RMS uses this field in conjunction with 
the XAB$L_LOC field and with the XAB$W_RFI field to provide precise 
positioning control of the area or area extension. 

The XAB$B_ALN field is a keyword value field in which an alignment 
boundary option is defined by a symbolic constant value. For example, the 
cylinder boundary option has a symbolic constant value of XAB$C_CYL. 

Note that if no value is defined for this field, VMS RMS assumes the 
XAB$C_ANY option (no additional positioning control desired). Additional 
positioning control is not supported for DECnet operations. 

The XAB$B—ALN field corresponds to the FDL attribute AREA POSITION. 

The following list describes the options for the XAB$B_ALN field: 

Options 

XABSC^NY 

Any allocation; specifies that no positioning control over the area is desired. If 
this option is selected, the XAB$L_LOC and XAB$W__RFI fields are ignored. 

This option corresponds to the FDL attribute AREA POSITION NONE. 
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8.3 XAB$B-ALN Field 


XAB$C_CYL 

Specifies that the area boundary begin at the cylinder number identified by 
the location field XAB$L_LOC. 

This option corresponds to the FDL attribute AREA POSITION CYLINDER. 

XAB$C-LBN 

Specifies that the area boundary begin at the logical block number identified 
by the location field XAB$L_LOC. 

This option corresponds to the FDL attribute AREA POSITION LOGICAL. 

XAB$C_RFI 

This option is used only for extending an area. It specifies that the area 
extension begin as close as possible to the file identified by the related-file- 
identification field (XAB$W_RF1), and that the extent begin with the VBN 
specified by the location field XAB$L_LOC. 

This option corresponds to the FDL attribute AREA POSITION FILE_ID or 
AREA POSITION FILE-NAME. If you try to use this option with DECnet 
operations, VMS RMS automatically replaces it with the XAB$C_ANY option. 

XAB$C_VBN 

This option applies to area extension only. It specifies that the area extension 
begin as close as possible to the virtual block number identified by the 
location field XAB$L_LOC. 

This option corresponds to the FDL attribute AREA POSITION VIRTUAL. 


8.4 XAB$L_ALQ Field 

This field defines the number of blocks to be initially allocated to an area 
when it is created using a Create service, or the number of blocks to be added 
to an area when it is explicitly extended using an Extend service (as opposed 
to automatic extension). In both cases, this field overrides the allocation 
quantity in the associated FAB (see Chapter 5). 

The XAB$L_ALQ field accepts numeric values of up to 4,294,967,295 for 
initial allocation, but the allocation is limited by the number of blocks 
available on the device. 

When you create a new area using the Create service, VMS RMS interprets 
the value in the XAB$L_j\LQ field as the number of blocks for the area's 
initial extent. If the value is 0, VMS RMS allocates a minimum number of 
blocks depending on the file organization. For example, VMS RMS allocates 
only the number of blocks needed for the key and area definitions with 
indexed files. 

When you use either the Create or Extend services with indexed files, VMS 
RMS rounds the allocation quantity value up to the next cluster boundary 
and returns this value to the program in the XAB$L_-ALQ field. VMS RMS 
uses this value as the extension value when you extend an existing area using 
the Extend service, unless the program changes the value before invoking the 
Extend service. Note that the value 0 is not acceptable for extending an area. 
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8.5 XAB$B_AOP Field 

The allocation options (AOP) field lets you specify a particular type of 
allocation. 

This field is a binary options field where one or more options may be selected 
by setting the appropriate bits. Each option is identified by a symbolic offset 
and has a mask value; for example, the CBT option has an offset of XAB$V_ 
CBT and a mask value of XAB$M_CBT. 

The options for the XAB$B_AOP field are summarized in the following list. 

Options 

XAB$V_CBT 

Contiguous best try; indicates that the allocation or extension should use 
contiguous blocks, on a "best effort" basis. This option overrides the FAB$L_ 
FOP field FAB$V_CBT option. 

This option corresponds to the FDL attribute AREA BEST_TRY_ 
CONTIGUOUS. 

XAB$V_CTG 

Contiguous; indicates that the initial allocation extension must use contiguous 
blocks only; the allocation fails if the requested number of contiguous blocks 
is not available. If this is the initial allocation and only a single area is 
specified, the file is marked contiguous. This option overrides the FAB$L_ 
FOP field FAB$V_CTG option. 

This option corresponds to the FDL attribute AREA CONTIGUOUS. 

XAB$V_HRD 

Hard; indicates that if the requested alignment cannot be performed, an error 
will be returned. By default, the allocation is performed as near as possible to 
the requested alignment. 

Note that the XAB$V_HRD option is applicable only to XAB$C_CYL and 
XAB$C_LBN alignment boundary types, specified by the XAB$B_ALN field. 

This option corresponds to the FDL attribute AREA EXACT-POSITIONING. 

XAB$V_OIMC 

On cylinder boundary; indicates that VMS RMS is to begin the allocation on 
any available cylinder boundary. 

This option corresponds to the FDL attribute AREA POSITION ANY— 
CYLINDER. 
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XAB$B_BKZ Field 

When VMS RMS creates relative and indexed files, this field specifies bucket 
size using numeric values ranging from 0 through 63 to represent the number 
of blocks in a bucket. If this argument is omitted, or if a value of 0 is 
inserted, VMS RMS uses a default size equal to the minimum number of 
blocks required to contain a single record. For RMS-11 processing, the bucket 
size must be less than or equal to 32 blocks. 

When calculating the bucket size, you must consider the control information 
(overhead) associated with each bucket. Note that some record types contain 
control bytes and to calculate the overhead you must multiply the number of 
records per bucket by the number of control bytes per record. See the Guide 
to VMS File Applications for more information. 

The FDL editor can be used to calculate efficient bucket sizes for indexed files. 
(For information about the FDL editor, see the VMS File Definition Language 
Facility Manual. 

When you create a file, VMS RMS uses this field as input to determine the 
specified bucket size and upon conclusion, uses the field to output the bucket 
size. Because relative files are limited to one area, this field specifies the size 
for all buckets in the file. For indexed files, you can specify a different size 
for each area using this field in the appropriate XABALL. 

When you open an existing file, VMS RMS uses this field to output the bucket 
size to your program. 

The value in this field overrides the contents of the bucket size field of the 
FAB on a Create service (see Chapter 5). 

You can specify multiple areas for a single index by having the XAB$B-JAN 
and XAB$B_LAN fields in the key definition XAB (XABKEY) indicate that the 
lowest level of the index and the remainder of that index occupy different 
areas (defined by different XABALLs). However, the number of blocks 
per bucket (XAB$B_BKZ value) must be the same for the entire index of a 
particular key. If multiple areas are specified for an index and if the XAB$B_ 
BKZ values are not the same, VMS RMS returns an error because the values 
for one index must be the same. However, if you specify the XAB$B_BKZ 
field for at least one area and use the default (0) for the XAB$B_BKZ field 
of a different area (or areas) of the same index, VMS RMS uses the largest 
XAB$B_BKZ value specified among the XABALL control blocks to determine 
the bucket size for that index. 

This field corresponds to the FDL attribute AREA BUCKET__SIZE. 


XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABALL, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ALLEN (this is done by the $XABALL macro). 
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8.8 XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block as 
a XABALL. Once set, this field must not be altered unless the control block 
is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ALL (this is done by the $XABALL macro). 


8.9 XAB$W_DEQ Field 

The default extension quantity (DEQ) field specifies the number (0 to 65,535) 
of blocks to be added when VMS RMS automatically extends the area. If you 
specify 0, the VMS RMS provides a default extension value. 

The value in this field overrides the contents of the default extension quantity 
field of the FAB (see Chapter 5). 

This field corresponds to the FDL attribute AREA EXTENSION. 


8.10 XAB$L_LOC Field 

The location (LOC) field contains a numeric value that indicates the beginning 
point for area allocation. VMS RMS refers to the location field when 
executing a Create or Extend service, but only if the XAB$B_ALN field 
specifies an alignment option. The way the XAB$L-_LOC field is used 
depends on the value specified for the XAB$B_ALN field (a binary options 
field). The beginning point for the allocation is determined as follows: 

• If the XAB$B_ALN field XAB$C—CYL option is specified, the location 
number is the cylinder number (0 through the maximum cylinder number 
on the volume) where the allocation begins. 

• If the XAB$B_ALN field XAB$C_LBN option is specified, the location 
number is the logical block number (0 through the maximum number of 
blocks on the volume) where the allocation begins. 

• If the XAB$B_ALN field XAB$C_VBN or XAB$C_RFI option is specified, 
the location number is the virtual block number (1 through the maximum 
number of blocks in the file) where the allocation begins. This applies 
only to the Extend service. If the number 0 is specified, or if the number 
is omitted during an Extend service, VMS RMS places the file extension 
as near to the end of the file as possible. 

This field corresponds to the FDL attribute AREA POSITION. 


8.11 XAB$L_NXT Field 

The next XAB address (NXT) field specifies the symbolic address of the next 
XAB in the XAB chain. A value of 0 (the default) indicates that the current 
XAB is the last (or only) XAB in the chain. 
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8.12 XAB$W_RFI Field 

The related file identification (RFl) field allows you to position files or areas of 
an indexed file close to a specified file. 

This field contains the 3-word file identification value of the related file. 

A value of 0,0,0 (the default) indicates that the current file is to be used. 
Specifying the XAB$B_ALN field XAB$C_RFI option and specifying the 
XAB$W_RF1 field as 0,0,0 are equivalent to specifying the XAB$B_ALN field 
XAB$C_VBN option. 

You can view the file identification of a file using the DCL command 
DIRECTORY with the /FULL qualifier. 

The file is created or extended as near to the specified related file as possible 
at the virtual block number specified by the LOC argument. 

The XAB$W_RF1 field is ignored unless the XAB$B_ALN field is set to 
XAB$C_RFI. It is also ignored for DECnet operations. 

This field corresponds to the FDL attribute AREA POSITION FILE_ID or 
AREA POSITION FILE-NAME. 


8.13 XAB$W_VOL Field 

The relative volume number (VOL) field indicates the specific member of a 
volume set upon which the file is to be allocated. 

This field contains an integer in the range 0 through 255. The default is 0, 
specifying the "current" member of the volume set. 

Note that volume placement will be performed only if an alignment type in 
the XAB$B_ALN field is either XAB$C_CYL or XAB$C_LBN (you cannot 
specify XAB$C_VBN or XAB$C_RFI alignment types). If the XAB$B_ALN 
field contains a value of 0, placement of the file within the volume set will be 
at the discretion of the system, regardless of the contents of the XAB$W—VOL 
field. 

This field corresponds to the FDL attribute AREA VOLUME. 


8-7 








9 Date and Time XAB (XABDAT) 


The date and time XAB (XABDAT) block provides extended control of the 
date and time of the file's creation, revision (update), backup, and expiration. 


9.1 Summary of Fields 

VMS RMS sets certain values for date and time and returns them in XABDAT 
fields for your inspection. You can override these system-supplied values 
through the use of an XABDAT as input to a Create service. Note that date¬ 
time values are expressed in either absolute (positive) or delta (negative) 
format, and several system services are available for date-time conversion 
and use (see Example 3-1 in Chapter 3 of this manual and the VMS System 
Services Reference Manual). 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABDAT field are presented in Table 9-1. 


Table 9-1 XABDAT Fields 


Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

XAB$Q_BDT’ 

8 

DATE BACKUP 

Backup date and time 

xab$b_bln2 

1 

None 

Block length 

xab$q_cdt’ 

8 

DATE CREATION 

Creation date and time 

xab$b_cod2 

1 

None 

Type code 

XAB$Q_EDT 

8 

DATE EXPIRATION 

Expiration date and time 

XAB$L_NXT 

4 

None 

Next XAB address 

XAB$Q_RDT’ 

8 

DATE REVISION 

Revision date and time 

XAB$W_RVN’ 

2 

FILE REVISION 

Revision number 


’This field cannot be initialized by the $XABDAT macro. 

^This field is statically initialized by the $XABDAT macro to identify this control block as a 
XABDAT. 


Table 9-2 describes how the fields of the XABDAT block are used by the 
VMS RMS services. 
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Table 9-2 Services and the XABDAT Control Block 


Service 

XAB$Q BDT 

XAB$Q CDT 

XAB$Q EDT 

XAB$Q RDT, XAB$W RVN 

Close 

Not used 

Not used 

Not used 

Not used 

Create 

Input 

Input 

Input 

Input^ 

Display 

Output 

Output 

Output 

Output 

Erase 

Not used 

Not used 

Not used 

Not used 

Extend 

Not used 

Not used 

Not used 

Not used 

Open 

Output 

Output 

Output 

Output 


’The XAB$Q_RDT field for a Create service is superseded by the current date and time on a Close service. Use the 
XABRDT block to specify the XAB$Q_RDT field (see Chapter 15). 


The follovying notes apply to the use of XABDAT fields by VMS RMS services: 

1 If the user specifies the XAB$Q_CDT or XAB$Q_RDT field in the 
XABDAT as 0 (either explicitly or by default) and if the specified field is 
used as an input field by the service, it is replaced with the current date 
and time. 

2 If the Create service is invoked with a FAB that specifies the FAB$L_FOP 
field FAB$V_CIF (create-if) option and if the file to be created already 
exists, the Create service is processed like an Open service and the fields 
listed above are output fields. 

Each XABDAT field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 

The format and arguments of the $XABDAT macro and the $XABDAT_ 
STORE macro are described in Appendix B. 


9.2 XAB$Q_BDT Field 

The backup date and time (BDT) field contains a 64-bit binary value 
expressing the date and time when the file was most recently backed up. 
Note that this field is limited to a granularity of 1 second for remote files. 

This field corresponds to the FDL attribute DATE BACKUP. 


9.3 XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABDAT in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_DATLEN (this is done by the $XABDAT macro). 
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9.4 XAB$Q_CDT Field 


XAB$Q_CDT Field 

The creation date and time (CDT) field contains a 64-bit binary value 
expressing the date and time when the file was created. Note that this 
field is limited to a granularity of 1 second for remote files. 

This field corresponds to the FDL attribute DATE CREATION. 


XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block 
as an XABDAT. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_DAT (this is done by the $XABDAT macro). 


XAB$Q_EDT Field 

The expiration date and time (EDT) field contains a 64-bit binary value that 
indicates the date and time after which a file residing on a disk device may be 
considered for deletion by the system manager. For files residing on magnetic 
tape devices, the XAB$Q_EDT field sets the date and time after which you 
can overwrite the file. Note that this field is limited to a granularity of 1 
second for remote files. 

This field corresponds to the FDL attribute DATE EXPIRATION. 


XAB$L_NXT Field 

The next XAB address (NXT) field contains the symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 


XAB$Q_RDT Field 

The revision date and time (RDT) field contains a 64-bit binary value 
expressing the date and time when the file was last updated. Note that 
this field is limited to a granularity of 1 second for remote files. 

This field corresponds to the FDL attribute DATE REVISION. 


XAB$W_RVN Field 

The revision number (RVN) field contains a numeric value that indicates the 
number of times this file was opened for write operations. 

This field corresponds to the FDL attribute FILE REVISION. 












1 0 File Header Characteristic XAB (XABFHC) 


The file header characteristic XAB (XABFHC) contains information about a file 
that is stored in the file header. VMS RMS copies the file characteristics into 
this XAB whenever an Open or Display service executes. The XABFHC fields 
are then available for you to examine during processing. 

Note that for unshared sequential files, or sequential files shared using the 
FAB$V_UPI option, the values in the end-of-file block (XAB$L_EBK), first 
free byte in the end-of-file block (XAB$W_FFB), and longest record length 
(XAB$W_LRL) fields correspond to the values at the time of the last Close or 
Flush service. 

On a Create service, only the longest record length (XAB$W_LRL) field of this 
XAB is used as input, and then only if the record format is not fixed length. 
All other fields are used only as output from the VMS RMS services. 


10.1 Summary of Fields 

The symbolic offset, size, and a brief description of each RAB field are 
presented in Table 10-1. Note that many of these fields are also available in 
the FAB. 

Table 10-1 XABFHC Fields 


Field Offset 

Size 

(bytes) 

Description 

XAB$B_ATR' 

1 

Record attributes; equivalent to FAB$B_RAT 

XAB$B_BKZ' 

1 

Bucket size; equivalent to FAB$B_BKS 

XAB$B_BLN2 

1 

Block length 

XAB$B_C0D2 

1 

Type code 

XAB$W_DXQ’ 

2 

Default file extension quantity; equivalent to 
FAB$W_DEQ 

XAB$L_EBK’ 

4 

End-of-file block 

XAB$W_FFB' 

2 

First free byte in the end-of-file block 

XAB$W_GBC’ 

2 

Default global buffer count 

XAB$L_HBK’ 

4 

Highest virtual block In the file; equivalent to 
FAB$L_ALQ 

XAB$B_HSZ' 

1 

Fixed-length control header size; equivalent to 
FAB$B_FSZ 

XAB$W_LRL’ 

2 

Longest record length 


'This field cannot be initialized by the $XABFHC macro. 

^This field is statically initialized by the SXABFHC macro to identify this control block as a 
XABFHC. 
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Table 10-1 (Cont.) XABFHC Fields 
Size 

Field Offset (bytes) Description 

XAB$W_MRZ^ 2 Maximum record size; equivalent to FAB$W_ 

MRS 


XAB$L_NXT 

XAB$B_RF0^ 

XAB$L_SBN^ 


4 Next XAB address 

1 File organization and record format; combines 

FAB$B_RFM and FAB$B_ORG 

4 Starting logical block number for the file if it is 

contiguous; otherwise this field is 0 


XAB$W_ 

VERLIMIT^ 


Version limit for the file 


^This field cannot be initialized by the $XABFHC macro. 


Each XABFHC field is described below. There are no FDL equivalents for 
the XABFHC fields. Unless indicated otherwise, each field is supported for 
DECnet operations u^ing remote files with a VMS system as the remote node. 
Note that the words 'DECnet operations" in the following descriptions refer 
to remote file operations between two VMS systems. See the VMS Networking 
Manual for information about the support of VMS RMS options for remote 
file access to other syistems. 

The format and arguments of the $XABFHC macro and the $XABFHC_ 
STORE macro are described in Appendix B. 


XAB$B ATR Field 


The record attributes (ATR) field indicates the record attributes (special control 
information) associated with each record in this file. This field is equivalent 
to the FAB$B_RAT field. 


This field is a binary options field where each record attribute has a 
corresponding bit assignment. Options are identified using mnemonics. 

Each option in the field has its own symbolic offset and constant value. For 
example, the CR record attribute has the symbolic offset XAB$V_CR and the 
mask value XAB$M_iCR. The record attribute options are described in the 
following list: 

Options 

XAB$V_BLK 

Records do not cross block boundaries in sequential files. 

XAB$V_CR 

Each record is preced(?d by a line feed and followed by a carriage return. 

XAB$V_FTN 

Each record contains a FORTRAN (ASA) carriage return in the first byte. 

XAB$V_PRN 

Print file format. 
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10.2 XAB$B_ATR Field 


For more information about the XAB$B_ATR field, refer to the description of 
the FAB$B_RAT field in Chapter 5. 


10.3 XAB$B_BKZ Field 

The bucket size (BKZ) field specifies the number of blocks in each bucket of 
the file. It is equivalent to the FAB$B_BKS (or XAB$B_BKZ) field and is used 
only for relative or indexed files. 

This field contains a numeric value in the range of 0 to 63. 

For more information about the XAB$B_BKZ field, refer to the description of 
the FAB$B_BKS field in Chapter 5 and the description of the XAB$B_BKZ 
field in Chapter 8. 


10.4 XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABFHC, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_FHCLEN (this is done by the $XABFHC macro). 


10.5 XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block 
as an XABFHC. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_FHC (this is done by the $XABFHC macro). 


10.6 XAB$W_DXQ Field 

The default file extension quantity (DXQ) field specifies the number of blocks 
to be added when a disk file is extended automatically. This automatic 
extension occurs whenever your program performs a Put or Write service and 
the currently allocated file space is exhausted. 

This field is equivalent to the FAB$W_DEQ (or XAB$W_DEQ) field; it 
contains a numeric value in the range 0 through 65,535, which is rounded up 
to the value of the next cluster boundary. 

For more information about the XAB$W_DXQ field, refer to the description of 
the FAB$B_DEQ field in Chapter 5 and the description of the XAB$W_DEQ 
field in Chapter 8. 
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10.7 XAB$L_EBK Field 

When you open a file, VMS RMS stores the VBN of the physical block where 
the next record will be written in the XAB$L_EBK field. For example, assume 
that a file is allocated five physical blocks and that the last record written 
to the file is at byte OFFjg in the file's second physical block. When your 
program opens this file, VMS RMS stores the VBN of the second physical 
block in XAB$L_EBK and it stores lOOi^ in the XAB$W_FFB field. 

If the previous block is full when you open the file, VMS RMS stores the 
first location ( OOOjg) of the next block in XAB$W_FFB and the VBN of the 
next block in XAB$L_EBK. By way of contrast, in a similar situation RMS-11 
stores the last byte ( 200i6) of the filled block in the XAB$W_FFB field and 
the VBN of the filled block in the XAB$L_EBK field. 

The XAB$L_EBK field is meaningful for sequential files only. 

10.8 XAB$W_FFB Field 

The first free byte in the end-of-file block (FFB) field contains the byte location 
in the end-of-file block where the next record will be written. The XAB$W_ 
FFB field is meaningful for sequential files only. 

10.9 XAB$W_GBC Field ^ 

The default global buffer count (GBC) field contains the current global buffer 
count for this file. For more information about the XAB$W_GBC field, refer 
to the description of the FAB$W_GBC field in Chapter 5. 

This field is not supported for DECnet operations; it is ignored. 

10.10 XAB$L_HBK Field ^ ^ 

The highest virtual block (HBK) field contains the virtual block number 
currently allocated to this file. It is equivalent to the FAB$L_ALQ field 
after a Create, Open, or Display service executes. For sequential files, the 
difference between XAB$L_HBK and XAB$L_EBK equals the number of 
blocks in the file available for additional records without extending the file. 


10.11 XAB$B_HSZ Field 

The fixed-length control header size (HSZ) field indicates the length of the 
fixed portion for records in the VFC format. It is equivalent to the FAB$B_ 
FSZ field. 

This field contains a numeric value (1 to 255) that indicates, in bytes, the size 
of the fixed-length control area. This field is not applicable to indexed files. 

For more information about the XAB$B_HSZ field, refer to the description of 
the FAB$B_FSZ field in Chapter 5. 


10-4 








10.12 


10.13 


File Header Characteristic 

10.1 

XAB (XABFHC) 

2 XAB$W_LRL Field 

XAB$W_LRL Field 

The longest record length (LRL) field contains a i 
the longest record currently in the file, in bytes, 
sequential files only. 

numeric value that indicates 
This value is meaningful for 

XAB$W_MRZ Field 



The maximum record size (MRZ) field indicates the size of all records in a file 
with fixed-length records, the maximum size of variable-length records, the 
maximum size of the data area for variable with fixed-length control records, 
and the cell size for relative files. It is equivalent to the FAB$W_MRS field. 

This field contains a numeric value in the range applicable to the file type and 
record format (see Table 5-4), in bytes. 

For fixed-length records, the value represents the actual size of each record in 
the file. 


For variable-length records, the value represents the size of the largest record 
that can be written into the file. If the file is not a relative file, a value of 0 
is used to suppress record size checking, thus indicating that there is no user 
limit on record size. 


For variable with fixed-length control records, the value includes only the 
data portion; it does not include the size of the fixed control area. 

For more information about the XAB$W_MRZ field, refer to the description of 
the FAB$W_MRS field in Chapter 5. 


10.14 XAB$L_NXT Field 

The next XAB address (NXT) field contains the symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 


10.15 XAB$B_RFO Field 

The file organization and record format (RFO) field combines the FAB$B_ 
RFM and FAB$B_ORG fields using an inclusive OR. 
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10.15 XAB$B_RFO Field 


Record formats are listed below. 




Record Format 

Description 

FIX 

Fixed length 

STM 

Stream, delimited by FF, VT, LF, or CR LF 

STMCR 

Stream, delimited by CR 

STMLF 

Stream, delimited by LF 

UDF 

Undefined 

VAR 

Variable length 

VFC 

Variable length with fixed control area 

The file organizations are listed below. 

File Organization 

Description 

IDX 

Indexed sequential 

REL 

Relative 

SEQ 

Sequential 




For more information about the XAB$B_RFO field, refer to the description of 
the FAB$B_ORG field and the FAB$B_RFM field in Chapter 5. 


10.16 XAB$L_SBN Field 

The starting logical block number (SBN) field contains the starting logical 
block number for a contiguous file; if the file is not contiguous, this field 
contains 0. 

10.17 XAB$W_VERLIMIT Field ^ “ 

The file version limit <VERLIM1T) field contains the version limit for this file. 
This value is not available if the file was opened by file ID. 

This field is not supported for DECnet operations; it is ignored. 












'll Item List XAB(XABITM) 


The item list XAB (XABITM) provides a convenient means for using item list 
information to support VMS RMS functions. An item list consists of one or 
more entries that can represent either a control function or a sensing function 
that can be passed to the application program by way of the VMS RMS 
interface. 

Within the item list, you may not include a mix of control and sensing 
items related to various VMS RMS-supported functions. However, multiple 
XABITMs may be used. VMS RMS logically ignores items that are irrelevant 
to any particular function while acting on any item that is relevant. 

Each entry in the item list addressed by the XABITM is made up of three 
longwords and a longword 0 terminates the list. VMS RMS does not validate 
the item list. If the item list is invalid, VMS RMS returns a status of RMS$_ 
XAB in the RAB$L_STS field. Figure 11-1 illustrates the format for each 
entry in the item list. 


Figure 11-1 Item Descriptor Data Structure 


31 15 

0 

item code 

buffer length 

buffer address 


return length address 



ZK-1705-84 


You can locate the item list anywhere within the readable address space for 
a process but any buffers required by the related function must be located in 
read/write memory. 

The format and arguments of the $XABITM macro are defined in Appendix B. 

For VMS Version 5.0, the XABITM control block supports enhancements 
to network file access functions and enhancements to VMS RMS 
performance monitoring functions. Although the benefits derived from 
these enhancements are readily apparent, functional details are transparent to 
most users. 
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11.1 Summary of Fields 

The symbolic offset, size, and a brief description of each XABITM field are 
presented in Table 11-1. 


Table 11 -1 XABITM Fields 


Field Offset 

Size 

(Bytes) 

Description 

XAB$B_BLN' 

1 

Block length 

XAB$B_COD’ 

1 

Type code 

XAB$L_ITEMLIST 

4 

Item list address 

XAB$B_MODE 

4 

Set/sense control 

XAB$L_NXT 

4 

Next XAB address 


'This field is statically initialized by the $XABITM macro to identify the control block as an 
XABITM. 


11.1.1 XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABITM, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ITMLEN by the $XABITM macro. 


11.1.2 XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block 
as an XABITM. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ITM by the $XABITM macro. 


11.1.3 XAB$L_ITEMUST Field 

The item list address (ITEMLIST) field contains the symbolic address of the 
item list. 


11.1.4 XAB$L_MODE Field 

The item list mode (MODE) field specifies whether the items in the item list 
can be set by the program. It contains either the symbolic value XAB$K_ 
SETMODE or the symbolic value XAB$K_SENSEMODE (default). 


11.1.5 XAB$NXT Field 


The next XAB address (NXT) field contains the symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 
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11.2 Network File Access Items 

This section lists and briefly describes the items that support network file 
access features. 

Network items are effectively ignored for local operations. Although the 
application program may include network items in the XAB chain for the 
related FAB, VMS RMS does not consider any of the network-specific fields 
during local processing. Nor does VMS RMS return remote file contents to 
the application program during local file processing. 

Table 11-2 lists the entries in the XABITM item list relating to network file 
access features together with the buffer size required to store the data and a 
brief functional description. Note that although the application program can 
sense all of the item values from the VMS RMS interface, it can set only the 
following item values: 

• XAB$_NET_BLOCK_COUNT 

• XAB$_NET_EXTPROT 

• XAB$_NET_L1NK_TIME0UT 

• XAB$_NET_L1NK_CACHE_ENABLE 

• XAB$_NET_DATA_CRC_ENABLE 

• XAB$_UCHAR_C0NT1GB 

• XAB$_UCHAR_ERASE 

• XAB$_UCHAR_LOCKED 

• XAB$_UCHAR_NOBACKUP 

• XAB$_UCHAR_READCHECK 

• XAB$_UCHAR_WR1TECHECK 

Table 11-2 XABITM Item List __ 

Required 

Buffer 

Item Size Description_ 

XAB$_NET_BUFFER_SIZE 4 bytes The size of the buffer allocated for DAP messages 

between the local and remote node is a negotiated 
value that is decided by DAP. This informational item 
returns the actual buffer size, in bytes, allocated for 
DAP messages. The buffer size is slightly larger than 
the limit specified for the records being transferred. 
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11.2 Network File Access Items 


Table 11-2 (Cent.) XABITM Item List 


Require^ 

Buffer 

Size Description 

XAB$_NET_BLOCK_COUNT 4 bytes This is the value in blocks that the local node wants 

to use for buffering messages between itself and the 
remote node. 

DAP tries to allocate this buffer space at the local 
node; however, if the maximum buffer size at the 
remote node is smaller, DAP allocates buffer space 
based on the smaller value. When the remote system 
Incorporates VMS/FAL, It allows any size buffer up to 
32,767 bytes. 

The minimum buffer size for task-to-task network 
operations Is 4096 bytes. 

XAB$_NET_REMOTE_SYSTEI\/l 4 bytes This informational item returns the identity of the 

remote operating system using the symbolic constants 
listed in the following chart: 


Symbolic Constant 

Operating System 

XAB$K_RT11 

RT-11 

XAB$K_RSTS 

RSTS/E 

XAB$K_RSX11S 

RSX-11S 

XAB$K_RSX11M 

RSX-11M 

XAB$K_RSX11D 

RSX-11D 

XAB$K_IAS 

IAS 

XAB$K_VAXVMS 

VMS 

XAB$K_T0PS10 

TOPS-10 

XAB$K_T0PS20 

TOPS-20 

XAB$K_RSX1IMP 

RSX-11M-PLUS 

XAB$K_P_OS 

P/OS 

XAB$K_VAXELN 

VAXELN 

XAB$K_MS_DOS 

MS-DOS® 

XAB$K_ULTRIX_32 

ULTRIX-32 

XAB$K_SNA_OS 

SNA gateway to IBM® 


MS-DOS is a trademark of Microsoft Corporation. 

IBM is a registered trademark of International Business Machines, Inc. 
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11.2 Network File Access Items 


Table 11-2 (Cont.) XABITM Item List 


Item 

Required 

Buffer 

Size 

Description 

X AB$_NET_REMOTE _FILE _ 
SYSTEM 

4 bytes 

This Informational Item returns the Identity of the 
remote file system using the symbolic constants listed 
In the following chart: 


Symbolic Constant File System 


XAB$K_RMS11 

RMS-11 

XAB$K_RMS20 

RMS-20 

XAB$K_RMS32 

RMS-32 

XAB$K_FCS11 

FCS-11 

XAB$K_RT11FS 

RT-11 

XAB$K_NO_FS 

No file system present 

XAB$K_TOPS20FS 

TOPS-20 

XAB$K_TOPS10FS 

TOPS-10 

XAB$K_RMS32S 

RMS-32 subset (VAXELN) 

XAB$K_MS_DOSFS 

MS-DOS 

XAB$K_ULTRIX32_FS 

ULTRIX-32 

XAB$K SNA FS 

SNA gateway to IBM 


XAB$_NET_EXTPROT 8 bytes This item permits the application program to specify 

or to sense the extended file protection that is likely 
to be mapped to a protection subset supported by the 
remote system. The application program implements 
extended file protection as part of either a Create or 
Close service by specifying the appropriate protection 
mask In the related subfield: 


Subfield 

Protection 

XAB$W_SYSTEM_ACC 

System access 

XAB$W_OWNER_ACC 

Owner access 

XAB$W_GROUP_ACC 

Group access 

XAB$W WORLD ACC 

World access 
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11.2 Network File Access Items 


Table 11-2 (Cent.) XABITM Item List 


Requirecjl 

Buffer 

Size Description 


Each of the protection mask fields provides the 
following mask values for further defining access: 


Mask Value 

Protection Function 

XAB$M_RED_ACC 

Deny read access 

XAB$M_WRT_ACC 

Deny write access 

XAB$M_EXE_ACC 

Deny execute access 

XAB$M_DLT_ACC 

Deny delete access 

XAB$M_APP_ACC 

Deny append access 

XAB$M_DIR_ACC 

Deny directory access 

XAB$M_UPD_ACC 

Deny update access 

XAB$M_CHG_ACC 

Deny change protection 
access 

XAB$M EXT ACC 

Deny extend access 


XAB$_NET_SYSCAP_LOCAL 


XAB$_NET_SYSCAP_REMOTE 


XAB$_NET_DAPVER_LOCAL 


Note that not ail systems support all of the protection 
mask fields. 

8 bytes | This Informational item permits the appllcatin program 
! to read the network capabilities of the local system by 
returning symbolic bit vector values. See Table 11-3 
for a description of the network capabilities bit vectors 
used by the local and remote systems. 

8 bytes This informational item permits the application program 
to read the network capabilities of the remote 
system by returning symbolic bit vector values. See 
Table 11-3 for a description of the network capabilities 
bit vectors used by the local and remote systems. 

5 bytes This informational item returns the version of DAP on 
the local system using five symbolic bytes: 


Symbolic Byte 

Version Information 

; XAB$B_VER_DAP 

DAP protocol version 

i XAB$B_VER_ECO 

DAP protocol ECO level 

XAB$B_VER_CUS 

Customer modification level 
of DAP protocol; set to 0 by 
DIGITAL 

XAB$B_VER_DSV 

DIGITAL software version 
(release number) 

XAB$B_VER_CSV 

Customer software version 
number; set to 0 by 

DIGITAL 
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11.2 Network File Access Items 


Table 11-2 (Cont.) XABITM Item List 


Required 

Buffer 

Item Size Description__ 

The DAP version is 07-01-00-05-00 for VMS 
Version 5.0. 

XAB$_NET_DAPVER_REMOTE 5 bytes This informational item returns the version of DAP on 


the remote system using five symbolic bytes: 

Symbolic Byte 

Version Information 

XAB$B_VER_DAP 

DAP protocol version 

XAB$B_VER_ECO 

DAP protocol ECO level 

XAB$B_VER_CUS 

Customer modification level 
of DAP protocol; set to 0 by 
DIGITAL 

XAB$B_VER_DSV 

DIGITAL software version 
(release number) 

XAB$B_VER_CSV 

Customer software version 
number; set to 0 by 

DIGITAL 


XAB$_NET_LINK_TIMEOUT 4 bytes 


XAB$_NET_DATA_CRC_ENABLE 4 bytes 


XAB$_NET_LINK_CACHE_ENABLE 4 bytes 


XAB$_UCHAR_BADACL 

4 bytes 

X AB$_UCH AR _B ADBLOCK 

4 bytes 

XAB$_UCHAR_CONTIG 

4 bytes 

XAB$_UCHAR_CONTIGB 

4 bytes 

XAB$_UCHAR_D1RECT0RY 

4 bytes 

XAB$_UCHAR_ERASE 

4 bytes 

XAB$_UCHAR -LOCKED 

4 bytes 

XAB$_UCHAR_MARKDEL 

4 bytes 

XAB$_UCHAR_NOBACKUP 

4 bytes 

XAB$_UCHAR_READCHECK 

4 bytes 

XAB$_UCHAR_SPOOL 

4 bytes 

AB$UCHAR WRITECHECK 

4 bytes 


This item permits the application program to set the 
timeout interval for logical link caching. The setting is 
passed as the number of seconds used to cache the 
logical link. A zero (0) setting enables caching until 
image rundown. The default Interval Is 30 seconds. 

This Item allows the application program to enable 
cyclic redundancy checking at the DAP level. The 
symbolic value XAB$K_ENABLE enables CRC checking 
at the DAP level (the default state); the symbolic value 
XAB$K_DISABLE disables CRC checking at the DAP 
level. 

This item is used to enable or to disable logical link 
caching. The symbolic value XAB$K_ENABLE enables 
link caching (the default state); the symbolic value 
XAB$K_DISABLE disables link caching. 

File's ACL is corrupt. 

File contains bad blocks. 

File is contiguous. 

Keep the file as contiguous as possible. 

File is a directory. 

Erase the file's contents before deleting it. 

File is deaccess-locked. 

File is marked for deletion. 

Do not back up the file. 

Verify read operations to the file. 

File Is an intermediate spool file. 

Verify write operations to the file. 
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11.2 Network File Access Items 


The system capabilities supported by various DAP implementations are 
described using a vector of bits wherein a bit is set if the corresponding 
capability is supported. Any attempt to implement a feature at the local 
node that is not supported at the remote node is treated as a protocol 
error. Table 11-3 describes the bit vectors that VMS RMS uses to return 
the networking capabilities for both the local and remote nodes to the calling 
program. Capabilities supported by Version 5.0 of VMS are appropriately 
footnoted. 


Table 11-3 System Networking Capabilities 


Bit Value 

Capability 

XAB$V_CAP_FILALL' 

Allocation of space at file creation 

XAB$V_CAP_SEQORG' 

Sequential file organization 

XAB$V_CAP_RELORG' 

Relative file organization 

XAB$V_CAP_EXTEND' 

Manual file extension 

XAB$V_CAP_SEQFIL’ 

Sequential file access (file transfer mode) 

XAB$V_CAP_RANRRN’ 

Random access by relative record number 

XAB$V_CAP_RANVBN' 

Random access by virtual block number 

XAB$V_CAP_RANKEY’ 

Random access by key value 

XAB$V_CAP_RANRFA' 

Random access by record file address 

XAB$V_CAP_IDXORG' 

Multikeyed indexed file organization 

XAB$V_CAP_SWMODE' 

Dynamic switching of access modes 

XAB$V_CAP_APPEND' 

Records appended to end of file 

XAB$V_CAP_SUBMIT’ 

Command file submission/execution 

XAB$V_CAP_MDS 

Multiple data streams for each file 

XAB$V_CAP_DISPLAY' 

Display of file attributes on request 

XAB$V_CAP_MSGBLK' 

Blocking of DAP messages up to response (less than 256 bytes) 

XAB$V_CAP_UNRBLK 

Unrestricted blocking of DAP messages 

XAB$V_CAP_BIGBLK’ 

Blocking of DAP messages up to response (greater than or equal to 256 
bytes) 

XAB$V_CAP_DAPCRC’ 

DAP message CRC checksum 

XAB$V_CAP_KEYXAB’ 

Key definition XAB message 

XAB$V_CAP_ALLXAB’ 

Allocation XAB message 

XAB$V_CAP_SUMXAB' 

Summary XAB message 

XAB$V_CAP_DIRECTORY' 

Directory list operation 


'Supported for VMS Version 5,0. 
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11.2 Network File Access Items 


Table 11-3 (Cont.) System Networking Capabilities 


Bit Value 

XAB$V_CAP_TIMXAB’ 

XAB$V_CAP_PROXAB’ 

XAB$V_CAP_FOPSPL' 

XAB$V_CAP_FOPSCF' 

XAB$V_CAP_FOPDLT' 

XAB$V_CAP_SEQRAC’ 

XAB$V_CAP_BITOPT 

XAB$V_CAP_WARNING 

XAB$V_CAP_RENAME' 

XAB$V_CAP_WILDCARD’ 

XAB$V_CAP_GNGOPT 

XAB$V_CAP_NAMMSG' 

XAB$V_CAP_SEGMSG 

XAB$V_CAP_CHGATTCLS 

XAB$V_CAP_CHGTIMCLS' 

XAB$V_CAP_CHGPROCLS’ 

XAB$V_CAR_CHGNAMCLS 

XAB$V_CAP_MODATTCRE 

XAB$V_CAP_NAM3PART 

XAB$V_CAP_CHGATTREN 

XAB$V_CAP_CHGTIMREN 

XAB$V_CAP_CHGPROREN 

XAB$V_CAP_CTLBLKCNT^ 

XAB$V_CAR_OCTALVER 


Capability 

Date and time XAB message 

File protection XAB message 

Spool file on Close FOP option 

Submit command file on Close FOP option 

Delete file on Close FOP option 

Sequential record access 

Bit count option in the FLAGS field 

Warning status message and error recovery message exchange 

File rename operation 

Wildcard operations (excluding directory) 

Go/Nogo option In the ACCOPT field 
Name message 
Segmented DAP messages 

Changing file attributes on Close using ATT message 
Changing file attributes on Close using TIM message 
Changing file attributes on Close using PRO message 
Changing file attributes on Close using NAM message 
Modified attributes returned when file is created 

Three-part name message format in DISPLAY field of both Access and 
Control messages 

Changing file attributes on Rename using ATT message 
Changing file attributes on Rename using TIM message 
Changing file attributes on Rename using PRO message 
BLKCNT field in Control message 
Octal version numbers only in file specifications 


^Supported for VMS Version 5.0. 


11.3 VMS RMS Performance Monitoring 

This section describes the implementation of VMS RMS performance 
monitoring from the VMS RMS interface using a XABITM. 

To explicitly obtain VMS RMS performance statistics for a file through the 
VMS RMS interface, the application program enables the statistics function 
using the XAB$_STAT_ENABLE item. This item may contain either the 

symbolic value XAB$K_DISABLE (default) or XAB$K—ENABLE. The XAB$— 

RTA T E NABLE item may be used on $CREATE to initially mark the file 
for statistics gathering, or it may be used in $DISPLAY (or implied display) 
operations to sense the statistics monitoring state. 
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11,3 VMS RMS Performance Monitoring 



You can enable statistics for an existing file from the DCL interface using 
the SET FILE command. See the VMS DCL Dictionary for details. For 
details about using the Monitor Utility for gathering VMS RMS performance 
statistics, see the VMS Monitor Utility Manual. 

Example 11-1 illustrates the use of XABITM to enable statistics monitoring: 

Example 11-1 Using XABITM to Enable VMS RMS Statistics 


ITEMLIST : BLOCK [ITM$S_ITEM+4. BYTE] 
INITIALC REP (ITM$S_ITEM+4) OF (0) ), 

ITEM.XAB : $XABITM( mode = SETMODE, 
itemlist = ITEMLIST ), 


FILE_FAB : $FAB( 


ITEM.BUFFER : LONG INITIAL ( XAB$K_ENABLE); 


# 


XAB = ITEM.XAB, 


); 


ITEMLIST[ITM$W_ITMCOD] = XABS.STAT.ENABLE; 
ITEMLIST[ITM$W_BUFSlZ] = 4; 

ITEMLIST[ITM$L_BUFADR] = ITEM.BUFFER; 
$CREATE( fab = FILE.FAB ); 
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12 Journaling XAB(XABJNL) 


The journaling XAB ($XABJNL) control block supports file journaling 
operations. See the VAX RMS Journaling Manual for details. 
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1 3 Key Definition XAB (XABKEY) 


You must provide a key definition XAB (XABKEY) for each key in an indexed 
file in order to define the key's characteristics. Before you create an indexed 
file, you must establish the contents of the XABKEY fields for the primary key 
and for each alternate key. 

When you invoke an Open or Display service for an existing indexed file, you 
can use XABKEYs if you want to provide your program with one or more 
of the key definitions specified when the file was created. Alternatively, the 
summary XAB (see Chapter 17) provides the number of keys, number of 
allocated areas, and the prolog version assigned to the file. 


13.1 Summary of Fields 

Table 13-1 lists the symbolic offset, size, FDL equivalent, and a brief 
description of each XABKEY field. 


Table 13-1 XABKEY Fields 


Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

XAB$B_BLN’ 

1 

None 

Block length 

XAB$B_COD' 

1 

None 

Type code 

XAB$L_COLNAM 

4 

None 

Collating sequence name 

XAB$L_COLSIZ 

4 

None 

Collating sequence table size 

XAB$L_COLTBL 

4 

COLLATING-SEQUENCE 

Collating sequence table address 

XAB$B_DAN 

1 

KEY DATA-AREA 

Data bucket area number 

XAB$B_DBS2 

1 

None 

Data bucket size 

XAB$W_DFL 

2 

KEY DATA-FILL 

Data bucket fill size 

XAB$B_DTP 

1 

KEY TYPE^ 

Data type of the key 

XAB$L_DVB^ 

4 

None 

First data bucket virtual block number 

XAB$B_FLG 

1 

KEY^ 

Key options flag 

XAB$B_IAN 

1 

KEY INDEX-AREA 

Index bucket area number 

XAB$B_IBS2 

1 

None 

Index bucket size 

XAB$W_IFL 

2 

KEY INDEX-FILL 

Index bucket file size 

XAB$L_KNM 

4 

KEY NAME 

Key name buffer address 

XAB$B_LAN 

1 

KEY LEVEL1_INDEX_ 
AREA 

Lowest level of index area number 

XAB$B_LVL2 

1 

None 

Level of root bucket 


^This field is statically initialized by the SXABKEY macro to Identify this control block as an XABKEY. 
^This field cannot be Initialized by the SXABKEY macro. 

^This field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 13-1 (Cont.) XABKEY Fields 


Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

XAB$W_MRL2 

2 

None 

Minimum record length 

XAB$B_NSG2 

1 

None 

Number of key segments 

XAB$B_NUL 

1 

KEY NULL_VALUE 

Null key value 

XAB$L_NXT 

4 

None 

Next XAB address 

XAB$W_POSn 

2 

KEY POSITION and 
SEGn_POSITION 

Key position, XAB$W_POSO to 
XAB$W_POS7 

XAB$B_PROLOG 

1 

KEY PROLOG 

Prolog level 

XABSB-REF'^ 

1 

KEY n 

Key of reference 

XAB$L_RVB2 

4 

None 

Root bucket virtual block number 

XAB$B_SlZn 

1 

KEY LENGTH and 
SEGn_LENGTH 

Key size XAB$B_SIZO to 

XAB$B_SIZ7 

XAB$B_TKS2 

1 

None 

Total key field size 


^This field cannot be initialized by the $XABKEY macro. 
"^For BLISS-32, this field is designated XAB$B_KREF. 


Each XABKEY field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 

The format and arguments of the $XABKEY macro and the $XABKEY-.STORE 
macro are defined in Appendix B. 


13.2 XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABKEY, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. The $XABKEY macro initializes the XAB$B_BLN 
field to the symbolic value XAB$C_KEYLEN. 


13.3 XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block as 
an XABKEY. Once set, this field must not be altered unless the control block 
is no longer needed. The $XABKEY macro initializes the XAB$B_COD field 
to the symbolic value XAB$C_KEY. 
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13.4 XAB$L_COLNAM Field 

When you invoke the Display service, VMS RMS uses this field to return a 
pointer to a memory buffer containing the name of the collating sequence for 
this key. 

The name buffer is in the form of an ASCII counted string where the first 
byte indicates the length of the name and the remaining bytes are the ASCII 
representation of the name itself. The maximum length of the buffer is 32 
bytes, one byte for the count and 31 bytes for the name. 


13.5 XAB$L_COLSIZ Field 

When you invoke the the Display service, VMS RMS returns the size, in 
bytes, of the collating sequence used with this key to this field. 


13.6 XAB$L_COLTBL Field 

VMS RMS provides you with a way to use alternative (non-ASCII) collating 
sequences with indexed file keys. You can define a collating sequence for 
each key of reference, yielding, for example, a file sorted in German by one 
key, French by another key, and so forth. 

This feature is based on the National Character Set Utility, which permits you 
to define alternative collating sequences for special characters and to establish 
and maintain a library of collating sequences. This eliminates having to 
redefine an alternative collating sequence when the application requires it. 
See the VMS National Character Set Utility Manual for details. 

Note: Key compression and index compression are not permitted with collating 
keys. 

To access an alternative collating sequence for a key, enter the symbolic 
address of the appropriate collating table in the XAB$L-_COLTBL field. For 
example, you might enter the following: 

DST^KEYO; 

SXABKEY 


COLTBL=FRENCH, - ;symbolic address of French collating table 


VMS RMS responds by storing the specified collating table in the initial blocks 
of the indexed file immediately following the area descriptors. Collating 
tables are typically about one block long. 

When you invoke the Display or the Open service, VMS RMS returns the 
address of the collating table in this field. 

This field corresponds to the FDL attribute COLLATING—SEQUENCE. 
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13.7 XAB$B_DAN Field 

The data bucket areaj number (DAN) field contains a numeric value that 
identifies the area where the data buckets for this key reside. The number 
reflects the value in tne XAB$B_AID field of the XABALL for this XAB chain. 
The numeric value rr^ay range from 0 through 254, but the default is 0; that 
is, area 0. 

When you create a new indexed file or when you use allocation XABs to 
define areas (see Chapter 8), you must specify a value for this field to identify 
the file area where the data buckets are to reside. 

When an XABKEY describes the primary key, the data level of the index 
consists of buckets that contain the actual data records of the file. However, 
when the key definition describes an alternate key, the data level of the index 
consists of buckets in which VMS RMS maintains pointers to the actual data 
records. 

The XAB$B_DAN field corresponds to the FDL attribute KEY DATA__AREA. 


13.8 XAB$B-DBS Field 

After an Open or Display service, the data bucket size (DBS) field contains the 
size of the data level (level 0) buckets, in virtual blocks, for the key described 
by the XAB. 


13.9 


XAB$W_DFL Field 


The data bucket fill sjze (DFL) field contains a numeric value that indicates 
the maximum numbef of bytes (of data) in a data bucket. The largest possible 
fill size is the bucket Mze, in blocks, multiplied by 512. The default value is 
0, which is interpretefi by VMS RMS as the maximum available space (that 
is, no unused space). If the specified size is not 0, but is less than one-half of 
the bucket size (in bytes), then the fill size used is one-half of the bucket size. 

When you create an indexed file, you use this field to specify the number 
of bytes of data you Want in each data level bucket. If you specify a value 
that is less than the actual bucket size, the data buckets contain some amount 
of free space. At run time, VMS RMS uses the fill size specified when the 
file was created only if the RAB$L_ROP (record-processing options) field 
RAB$V_LOA option js specified in the RAB; otherwise, VMS RMS fills the 
buckets. 


When an XABKEY de^ribes the primary key, the XAB$W_DFL field describes 
the space in the buckets containing actual user data records. When the 
XABKEY describes arJ alternate key, the XAB$W_DFL field describes the 
space in the buckets containing pointers to the user data records. 


It is advantageous to use the XAB$W_DFL field if you expect to execute 
numerous random Put and Update services on the file after it has been 
initially populated. You can minimize the movement of records (bucket 
splitting) by specifying less than the maximum bucket fill size when you 
create the file. To use the free space reserved in the buckets, programs that 
execute Put or Update services on the file should not specify the RAB$L_ 
ROP field RAB$V_LOA option. 
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This field corresponds to the FDL attribute KEY DATA JILL (which is 
expressed as a percentage). 


13.10 XAB$B_DTP Field 

The XAB$B_DTP field specifies the key data type and the key sort order, 
ascending or descending. 

In this keyword value field, each key data type option is defined by a 
symbolic value. If the key sort order is descending, the letter D is prefixed to 
the symbolic value; if the sort order is ascending, the prefix is omitted. For 
example, a XAB$B__DTP field having the value XAB$C-_DBN2 is an unsigned, 
2-byte binary number that is sorted in descending order. On the other hand, 
a XAB$B—DTP field having the value XAB$C_BN2 is an unsigned, 2-byte 
binary number that is sorted in ascending order. 

Only one option can be specified. It is identified by a symbolic constant 
value; for example, the STG (string) option has the constant value XAB$C-. 
STG. 

The options for the XAB$B JTP field are listed in the following chart: 


Keyword 

Data Type 

Sort Order 

XAB$C_BN2 

Unsigned 2-byte binary 

Ascending 

XAB$C_DBN2 

Unsigned 2-byte binary 

Descending 

XAB$C_BN4 

Unsigned 4-byte binary 

Ascending 

XAB$C_DBN4 

Unsigned 4-byte binary 

Descending 

XAB$C_BN8 

Unsigned 8-byte binary 

Ascending 

XAB$C_DBN8 

Unsigned 8-byte binary 

Descending 

XAB$C_IN2 

Signed 2-byte integer 

Ascending 

XAB$C_DIN2 

Signed 2-byte integer 

Descending 

XAB$C_IN4 

Signed 4-byte integer 

Ascending 

XAB$C_DIN4 

Signed 4-byte integer 

Descending 

XAB$C_IN8 

Signed 8-byte integer 

Ascending 

XAB$C_D1N8 

Signed 8-byte integer 

Descending 

XAB$C_COL 

Collating key 

Ascending 

XAB$C_DCOL 

Collating key 

Descending 

XAB$C_PAC 

Packed decimal string 

Ascending 

XAB$C_DPAC 

Packed decimal string 

Descending 

XAB$C_STG' 

Left-justified string of 
unsigned 8-bit bytes 

Ascending 

XAB$C_DSTG 

Left-justified string of 
unsigned 8-bit bytes 

Descending 


^This is the default value. 


The string data type may consist of from one to eight detached key field 
segments that collectively make up the key. For more information about 
segmented keys, see the descriptions of the XAB$W_POSO through XAB$W— 
POS7 field and the XAB$B_SIZ0 through XAB$B_SIZ7 field. 
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Integer, binary, and packed decimal key fields must be a contiguous set of 
bytes. 

The null value (that is, the XAB$V_NUL option in the XAB$B_FLG field is 
set) for the integer, binary, collating and packed decimal data types is 0, and 
the XAB$B_NUL field is ignored (see XAB$B_FLG and XAB$B_NUL). 

The formats of the binary and integer key field data types are presented 
below. 


Key Type 

Format 

XAB$C_BN2 

LSB at A, MSB at A+1 

XAB$C_DBN2 

LSB at A, MSB at A+1 

XAB$C_BN4 

LSB at A, MSB at A+3 

XAB$C_DBN4 

LSB at A, MSB at A+3 

XAB$C_BN8 

LSB at A, MSB at A+7 

XAB$C_DBN8 

LSB at A, MSB at A+7 

XAB$C_IN2 

LSB at A, MSB and sign at A+1 

XAB$C_D1N2 

LSB at A, MSB and sign at A+1 

XAB$C_IN4 

LSB at A, MSB and sign at A+3 

XAB$C_IN4 

LSB at A, MSB and sign at A+3 

XAB$C_IN8 

LSB at A, MSB and sign at A+7 

XAB$C_DIN8 

LSB at A, MSB and sign at A+7 


The collating key data types are used in conjunction with collating sequences 
located in the indexed file prolog. Collating sequences are used with 
multinational characters and are specified for each key. Note that key 
compression and index compression are not permitted with collating keys. 

A packed decimal string is a contiguous sequence of bytes specified by two 
attributes: the address (A) of the first byte of the string and a length (L) that 
is the number of digits in the packed decimal. The bytes of a packed decimal 
are divided into two 4-bit fields that must contain decimal digits, except for 
the first four bits (0 through 3) of the last (highest addressed) byte, which 
must contain a sign. The representation for the digits and signs is shown 
below. 





Digit or Sign 

0 

1 

2 

3 

4 

5 

6 
7 


Decimal Value 
0 

2 

3 

4 

5 

6 
7 


Hexadecimal Value 


0 

1 

2 

3 

4 

5 

6 
7 
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Digit or Sign 

Decimal Value 

Hexadecimal Value 

8 

8 

8 


9 

9 

9 


+ , 

10, 12, 14, or 15 

A, C 

:, E, or F 

- 

11 or 13 

B or 

D 


The preferred sign representation is 12 for plus ( + ) and 13 for minus (-). 
The length (L) is the number of digits in the packed decimal string (not 
counting the sign) and must be in the range 0 through 31. When the 
number of digits is even, an extra 0 digit must appear in the last four bits 
(4 through 7) of the first byte. Again the length in bytes of the packed 
decimal is L/2 + 1. The value of a zero-length packed decimal is 0; it contains 
only the sign byte, which also includes the extra 0 digit. 

The address. A, of the packed decimal specifies the byte containing the most 
significant digit in its high order. Digits of decreasing significance are assigned 
to increasing byte addresses and from high to low within a byte. Thus, +123 
has length 3 and is represented as follows: 


A 


A+1 


ZK-873-82 


7 4 3 0 


1 

2 

3 

12 


Similarly, -12 has length 2 and is represented as follows: 


A 

A+1 

ZK-874-82 

This field corresponds to the FDL attribute KEY TYPE. 


7 4 3 0 


0 

1 

2 

13 


13.11 XAB$L_DVB Field 

After an Open or Display service, the DVB field contains the starting virtual 
block number of the first data level bucket for the key described by the XAB. 
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13.12 XAB$B_FLG Field 

The key options flag (FLG) field specifies the following conditions: 

• Whether duplicate keys are permitted in the file 

• Whether a key value can change 

• Whether data is compressed 

• Whether string key options apply 

Primary key values cannot change, but alternate key values may change, 
depending on application requirements. Primary and alternate keys may be 
duplicated depending on the key field and the application. An alternate key 
field is more likely than a primary key field to use duplicates. 

This field is a binary options field where each key characteristic has a 
corresponding bit assignment. Multiple key characteristics can be associated 
with each key (multiple bits can be set). Each option in the field has its own 
symbolic offset and mask value. For example, the CHG key characteristic has 
a symbolic offset of XAB$V_CHG and a mask value of XAB$M_CHG. 

When you create an indexed file and are defining a string key, you can 
optionally specify the XAB$V_IDX_NCMPR, XAB$V_KEY__NCMPR, and 
XAB$V_NUL options. 

These are the options for the XAB$B-_FLG field: 

Options 

XAB$V_CHG 

The key value within the record in the file can be changed by a program 
during an Update service. This option can be specified only for alternate 
keys. 

This option corresponds to the FDL attribute KEY CHANGES. 

XAB$V_DAT_NCMPR 

Do not compress data. This option can be specified to override compression 
of data for Prolog 3 files for the primary key; that is, when XAB$__REF is 0. 

This option corresponds to the FDL attribute KEY DATA .-.RECORD- 
COMPRESSION. 

This option is not supported for DECnet operations; it is ignored. 

XAB$V-DUP 

The key value within the record in the file may have the same key value as 
another record (or other records) within the file. 

This option corresponds to the FDL attribute KEY DUPLICATES. 

XAB$V-IDX-NCMPR 

Do not compress index. This option can be specified to override compression 
of keys in the index for Prolog 3 files. This option is only valid if a string key 
is being defined. 

This option corresponds to the FDL attribute KEY INDEX—COMPRESSION 
and it is not supported for DECnet operations. 
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XAB$V_KEY_NCMPR 

Do not compress key. This option can be specified to override compression of 
each key for Prolog 3 files. For a primary key (XAB$_REF is 0), the primary 
keys at the data level are not compressed; for each alternate key (XAB$_REF 
is greater than 0), the secondary index data records (SIDRs) that point to the 
data record location are not compressed. This option is only valid if a string 
key is being defined. 

This option corresponds to the FDL attribute KEY DATA—KEY— 
COMPRESSION and it is not supported for DECnet operations. 

XAB$V-NUL 

When set, this bit refers VMS RMS to the XAB$B—NUL field to determine 
whether or not you have defined a null character for removing records from 
the related alternate index. This option can be specified only for alternate key 
indexes using string type keys. 

The defaults and combinations of allowing changeable key values (XAB$V— 
CHG option) and duplicate key values (XAB$V—DUP option) depend on 
whether a primary or alternate key is being defined by this XABKEY. The 
allowed combinations and defaults for duplicate and changeable key values 
are described below. 


Combinations 

Primary Key 

Alternate Key 

XAB$V_CHG and XAB$V_DUP both set 

Error 

Allowed 

XAB$V_CHG set, XAB$V_DUP clear 

Error 

Allowed 

XAB$V_CHG clear, XAB$V_DUP set 

Allowed 

Allowed 

XAB$V CHG and XAB$V DUP both clear 

Default 

Default 


By default, duplicate keys are not allowed for the primary key and its value 
cannot change. 

If the XABKEY control block is not initialized by the $XABKEY macro, then 
the defaults for alternate keys are the same as for primary keys and null key 
values are not used. However, if the XABKEY control block is initialized by 
the $XABKEY macro, the following defaults apply to alternate keys: 

• Duplicate key values are allowed. 

• Key values can change. 

• Null key values are not allowed. 

These defaults are applied only if the entire XAB$B—FLG field is defaulted. 

Note that VMS RMS supports alternate indexes that prohibit duplicate key 
values but do allow key values to change for Update services. Older versions 
of RMS-11 (in contrast to VMS RMS) do not allow this particular combination 
of attributes for alternate indexes. This factor should be considered when you 
create files with VMS RMS that may also be processed by RMS-11. 

This option corresponds to the FDL attribute KEY NULL—KEY. 
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13.13 XAB$B_IAN Field 

The index bucket area number (IAN) field contains a numeric value in the 
range 0 through 254, representing an area identification number contained in 
the XAB$B_AID field of an XABALL present in the same chain. The default 
is 0 (that is, area 0). 

When you create an indexed file, you use this argument to specify the area of 
the file that the index buckets are to reside in only when both of the following 
are true: 

• You are creating a new indexed file. 

• You are using allocation XABs to define areas. 

When the XABKEY describes the primary key, the index level of the index 
consists of all levels of the tree-structured primary index down to and 
including the level containing pointers to the user data records themselves. 
However, when the key definition describes an alternate key, the index 
level of the index comprises all levels of the tree-structured alternate index 
down to, but not including, the level containing buckets in which VMS RMS 
maintains pointer arrays describing the user data records. For directions about 
how to place the lowest level of the index in a location separate from the 
higher levels, see the description of the XAB$B_LAN field. 

This field corresponds to the FDL attribute KEY INDEX—AREA. 


13.14 XAB$B_IBS Field 

After an Open or Display service, the index bucket size (IBS) field contains 
the size of the index level (level 1 to n buckets, in virtual blocks, for the key 
described by the XAB). 


13.15 XAB$W_IFL Field 

The index bucket fill size (IFL) field contains a numeric value representing 
the maximum number of bytes in an index bucket. The maximum possible 
fill size is the bucket size, in blocks, multiplied by 512. The default value 
is 0, which is interpreted by VMS RMS as meaning the maximum available 
space (that is, no unused space). If the specified size is not 0, but is less than 
one-half of the bucket size (in bytes) then the fill size used is one-half of the 
bucket size. 

When you create an indexed file, you use this argument to specify the 
number of bytes you want in each index bucket. If you specify less than 
the total possible bucket size, you indicate that the index buckets are to 
contain some amount of free space. At run time, VMS RMS uses the fill size 
specified at creation time if the LOA option is specified in the RAB$L—ROP 
(record-processing options) field of the RAB; otherwise, VMS RMS fills the 
buckets. 

When an XABKEY describes the primary key, the XAB$W_IFL field describes 
the space in the buckets in all levels of the primary index down to and 
including the level containing pointers to the user data records. When an 
XABKEY describes an alternate key, the XAB$W—IFL field describes the space 
in the buckets in all levels of the alternate index down to, but not including. 
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the level containing buckets in which VMS RMS maintains pointer arrays 
describing the user data records. 

It is advantageous to use the XAB$W_IFL field if you expect to perform 
numerous random Put and Update services on the file after it has been 
initially populated. You can minimize the movement of index records (bucket 
splitting) by specifying less than the maximum bucket fill size when a file is 
created. To use the free space thereby reserved in the buckets, programs that 
invoke the Put or Update services for writing to the file should not specify 
the RAB$L_ROP field RAB$V_LOA option. 

This field corresponds to the FDL attribute KEY INDEX _FILL (which is 
expressed as a percentage). 


13.16 XAB$L_KNM Field 

The key name buffer address (KNM) field contains the symbolic address of a 
buffer that is available for assigning a user-specified name to the key being 
defined. The name buffer must be at least 32 bytes in length and you may 
use any 32-character string you choose to name the key field. 

If the default value is taken (0), VMS RMS assumes no name is to be 
assigned to the key. VMS RMS does not use this string but retains it in the 
file as part of the key definition information for documentation purposes. 

This field corresponds to the FDL attribute KEY NAME. 


13.17 XAB$B_LAN Field 

The lowest level of index area number (LAN) field contains a numeric value 
(0 through 254) representing an area identification number contained in the 
XAB$B_AID field of an XABALL present in the same XAB chain. If the 
XAB$B_LAN field is not specified (that is, if the value is 0), the value in the 
XAB$B-_IAN field is used as a default; in other words, the lowest level of the 
index occupies the same area of the file as the remainder of the index. 

This field permits you to separate the lowest level (level 1) of the index from 
all higher levels (levels 2+) of the index in an indexed file; you can use the 
XAB$B_LAN field to specify an area of the index wherein the lowest level of 
the index resides, separate from the area (or areas) specified by the XAB$B_ 
IAN field (wherein all other levels of the index reside). See XAB$B-_IAN for 
additional information. 

You can specify the XAB$B_LAN field only when both of the following 
conditions exist: 

• You are creating a new indexed file. 

• You are using allocation XABs to define areas. 

Note that the area specified by the XAB$B-_LAN field must have the same 
bucket size as the area specified by the XAB$B_IAN field. 

This field corresponds to the FDL attribute KEY LEVEL1_INDEX^AREA. 
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13.18 XAB$B_LVL Field 

Following an Open or Display service, the level of root bucket (LVL) field 
contains the level of the root bucket for the key described by the XAB. 


13.19 XAB$W_MRL Field 

Following an Open or Display service, the minimum record length (MRL) 
field contains the minimum record length (in bytes) needed to contain the key 
field for the key described by the XAB. 

If the key described by the XAB is the primary key (XAB$_REF is 0), then a 
record must be equal to or greater than the minimum record length returned 
in XAB$W_MRL to be inserted or updated in the file. 

If the key described by the XAB is an alternate key (XAB$_REF is greater 
than 0), then a record must be equal to or greater than the minimum record 
length returned in the XAB$W_MRL field to be recorded in the associated 
index for that alternate key. 


13.20 XAB$B_NSG Field 

Following an Open or Display service, the number of key segments (NSG) 
field contains the number of key segments that make up the key field for the 
key described by the XAB (see the XAB$W_POSO through XAB$W_POS7 
field). 


13.21 XAB$B_NUL Field 

Normally, VMS RMS updates all indexes to reflect the values in the 
corresponding key fields of the records written to an indexed file. The 
XAB$B_NUL field permits you to instruct VMS RMS not to make an entry 
in an alternate index if a record being entered in an indexed file contains a 
specified null alternate key value. To specify the XAB$B_NUL field, three 
conditions must be satisfied: 

• The XABKEY must define an alternate key. 

• The XAB$B_FLG field XAB$V_NUL option must be set when you create 
the file (see XAB$B_FLG). 

• The key data type must be string. 

You can use any ASCII character in the null (NUL) field if you are defining a 
string-type alternate key. The default null value for string-type alternate keys 
is 0 and nonstring keys always use 0 for the null value. 

This field corresponds to the FDL attribute KEY NULL_VALUE. 


13.22 XAB$L_NXT Field 

The next XAB address (NXT) field contains the symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 
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13.23 XAB$W_POSO Through XAB$W_POS7 Field 

There are two types of keys, simple keys and segmented keys. 

« 

A simple key is made up of one or more contiguous bytes and it may be used 
with any data type, including the string data type. For simple keys, the first 
byte of the key position field contains a numeric variable whose value relative 
to 0 defines the starting position of the key. The remaining bytes contain 
zeros. 

Segmented keys include two through eight strings of key data (segments) and 
can only be used with string data type key fields. The key segments need 
not be contiguous nor must they be in a particular order. Key segments may 
overlap except for primary keys used with Prolog 3 files. If your application 
requires overlapping key segments in a Prolog 3 file, consider using an 
alternate segmented key. If you must have a primary key with overlapping 
segments, VMS RMS requires you to use either a Prolog 2 or Prolog 1 
structure (which it automatically assigns if the XAB$B_PROLOG field is not 
specified). 

For segmented keys, the first word of the key position field specifies the 
starting position of the first segment and each succeeding byte specifies the 
starting position of one of the remaining segments. When processing records 
that contain segmented keys, VMS RMS regards a segmented key field as a 
single, logically contiguous string beginning with the first segment and ending 
with the last. 

You should note that the XAB$W_POSO through XAB$W_POS7 and the 
XAB$B_SIZ0 through XAB$B_SIZ7 (key size) fields must define the same 
number of key position values and key size values. 

This field corresponds to the FDL attributes KEY POSITION and SEGn_ 
LENGTH. 


13.24 XAB$B_PROLOG Field 

The prolog (PROLOG) field defines the version or structure level of the file 
index. It contains a numeric value from 0 through 3. 

The XAB$B_PROLOG field is input to the Create service, and it is returned 
by the Display and Open services. 

This field must only be used to define a primary key. 

Prolog 3 is the default prolog level, unless the primary key contains 
overlapping segments. VMS RMS examines the key characteristics and 
determines the correct prolog structure to apply to the file. If the XAB$B^ 
PROLOG field is not specified (that is, if the value is 0), the process default 
prolog level is examined, then the system default prolog level is used. These 
default values are set by the DCL command SET RMS_DEFAULT/PROLOG. 

You should not specify a prolog level 1 because VMS RMS decides whether 
a Prolog 1 or Prolog 2 file should be created, depending on the key type 
defined for the file. If you want to select a prolog level other than Prolog 3, 
you should select either 0 or 2. 

For more detailed information regarding the options for selecting a specific 
prolog level, see the description of the Create service in Part III. 
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This field corresponds to the FDL attribute KEY PROLOG and it is not 
supported for DECnet operations; the default prolog in effect at the remote 
node is used. 


13.25 XAB$B_REF Field 

The key of reference (REF) field defines a key as either the primary key or 
some alternate key. 

Note: For BLISS-32, this field is designated XAB$B_KREF. 

This field contains a numeric value in the range 0 through 254. A value of 0 
indicates that this is the primary key; a value of 1 indicates the first alternate 
key; a value of 2 indicates the second alternate key, and so on. The order of 
the XABKEYs is irrelevant. 

Note that VMS RMS can process an indexed file with 255 defined keys; each 
defined key field, however, has an associated cost in processing and I/O 
time. The time required to build and maintain the index for the key field 
and the disk storage required to contain the index for each key field should 
be considered when you decide whether the field should be an alternate key 
field. A file with six to eight defined keys (the primary key and five to seven 
alternate keys) should be considered as a maximum; a file with two or three 
defined keys is typical. 

This field corresponds to the FDL attribute KEY n where n is the number of 
the key being defined). 


13.26 XAB$L_RVB Field 

After an Open or Display service, the root index bucket virtual block number 
(RVB) field contains the virtual block number for the root bucket of the index 
for the key described by the XAB. 


13.27 XAB$B_SIZO Through XAB$B_SIZ7 Field 

The key size (SIZ) field defines the length of the key field within each record. 
This field contains a numeric value representing the length, in bytes, of the 
key within the record. Up to eight values can be assigned; maximum values 
depend on the type of key. 

The XAB$B_SIZ0 through XAB$B__SIZ7 field defines the length (in bytes) 
of the key whose starting position is defined in the key position field of the 
XAB. Two types of keys can be defined: simple and segmented (see the 
XAB$W_POSO through XAB$W_POS7 field). 

For a simple key, the XAB$B_SIZ0 through XAB$B_SIZ7 field contains only 
one key size value (in XAB$B_SIZ0). 

For a segmented key, the XAB$B_SIZ0 through XAB$B_SIZ7 field contains 
a key size value for each segment of the key. You should note that the 
XAB$B__SIZ0 through XAB$B_SIZ7 field and the XAB$W_POSO through 
XAB$W_POS7 field must contain the same number of key size values and 
key position values. VMS RMS associates the first key position value with the 
first key size value to define the location and length of the first segment of a 
segmented key, and so forth. 
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€ 


When the data type of the key is string, the total size (sum of all sizes) of the 
key must be less than 256 bytes. 

When the data type of the key is 2-byte integer or 2-byte binary, XAB$B_ 
SIZO must equal 2 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If 
the size is 0, it defaults to 2. 

When the data type of the key is 4-byte integer or 4-byte binary, XAB$B__ 
SIZO must equal 4 and XAB$B_SIZ1 through XAB$B__SIZ7 must contain 0. If 
the size is 0, it defaults to 4. 

When the data type of the key is 8-byte integer or 8-byte binary, XAB$B-> 
SIZO must equal 8 and XAB$B__SIZ1 through XAB$B_SIZ7 must contain 0. If 
the size is 0, it defaults to 8. 

When the data type of the key is packed decimal, the size specified by 
XAB$B_SIZ0 must be from 1 through 16, and XAB$B-.SIZ1 through XAB$B_ 
SIZ7 must contain 0. 

This field corresponds to the FDL attribute KEY LENGTH or KEY SEGn_ 
LENGTH where n is the number of the segment being defined. 


13.28 XAB$B_TKS Field 

After an Open or Display service, the total key size (TKS) field contains the 
total key size (the sum (in bytes) of XAB$B_SIZ0 through XAB$B_SIZ7) for 
the key described by the XAB. 
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1 4 Protection XAB (XABPRO) 


The protection XAB (XABPRO) specifies the ownership, accessibility and 
protection for a file. Although an XABPRO is typically used as input to 
the Create service, you can use it to change the protection of a file when 
you execute the Close service if you have write access to the file and have 
accessed the file for some type of modification (Put, Update, Delete, or 
Truncate). 


14.1 Summary of Fields 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABPRO field are presented in Table 14-1. 


Table 14-1 XABPRO Fields 


Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

XAB$L_ACLBUF 

4 

None 

Address of buffer that contains ACL 

XAB$L_ACLCTX 

4 

None 

ACL positioning context 

XAB$W_ACLLEN 

2 

None 

Receives the length of an ACL during 
an Open or Display service 

XAB$W_ACLSIZ 

2 

None 

Length of buffer containing binary ACEs 

XAB$L_ACLSTS 

4 

None 

System error status for ACL processing 

XAB$B_BLN’ 

1 

None 

Block length 

XAB$B_COD' 

1 

None 

Type code 

XAB$W_GRP2 

2 

FILE OWNER 

Group number of file owner 

XAB$W_MBM^ 

2 

FILE OWNER 

Member number of file owner 

XAB$B_MTACC 

1 

FILE MT_PROTECTION 

Magnetic tape accessibility 

XAB$L_NXT 

4 

None 

Next XAB address 

XAB$W_PRO 

2 

FILE PROTECTION 

File protection; contains four separate 
fields denoting protection for system, 
owner, group, and world 

XAB$B_PROT_OPT 

1 

None 

File protection options 

XAB$L_UIC 

4 

FILE OWNER 

User identification code; contains both 
the group and member fields 

^This field is statically initialized by the $XABPRO macro to identify this control block as an XABPRO. 

^This field cannot be initialized by the $XABPRO macro. 
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Each XABPRO field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual 

The format and arguments of the $XABPRO macro and the $XABPRO_ 
STORE macro are defined in Appendix B. 


14.2 XAB$L_ACLBUF Field 

The ACL buffer field (ACLBUF) stores the address of a buffer area that 
contains an access control list (ACL) for this file. The ACL buffer contains one 
or more access control entries (ACE) in binary format. The system processes 
the ACL until it encounters an ACE with a length byte value of 0 or until 
it reaches the end of the buffer as indicated by XAB$W__ACLSIZ. The ACL 
buffer is used as input to a Create service and as output from an Open or 
Display service. The address in XAB$L—ACLBUF is used only as input to 
these services. 

During a Create operation, if the XAB$L—ACLBUF field has a value other 
than 0, VAX RMS attempts to create the file using the value in the ACL 
buffer. When the XAB$L—ACLBUF field has a value of 0 during a Create 
operation, the file has an ACL only if an ACL is specified by the systemwide 
defaults. Once a file has been created, the ACL cannot be changed using 
VMS RMS. 

During an Open or a Display operation, if the XAB$L—ACLBUF field has a 
value other than 0, VMS RMS passes this address to the file system. The file 
system then fills the user's buffer with the file's ACL (in binary format). If 
the entire ACL does not fit into the user's buffer the file system puts only as 
many ACEs into the buffer as possible. (See the XAB$L—ACLCTX field for 
more information.) 

You can convert an ASCII ACL to binary format by using the SPARSE—ACL 
system service, and you can convert an ACL from binary format to ASCII 
using the $FORMAT—ACL system service. For information about using the 
SPARSE—ACL and SFORMAT—ACL services, see the VMS System Services 
Reference Manual 

The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


14.3 XAB$L_ACLCTX Field 

The XABSL—ACLCTX field is used as a place holder by VMS RMS, and it 
is used as an input and output field by VMS RMS during Open and Display 
operations when the XAB$L—ACLBUF field has a value other than 0. In 
order to read an ACL beginning with the first ACE, the XAB$L—ACLCTX 
field must have a value of 0. When the initial Open or Display operation is 
complete, VMS RMS fills the XAB$L—ACLCTX field with a value that serves 
as a context field, allowing subsequent Open or Display operations that read 
the remainder of the ACL (if the entire list of ACEs did not fit into the user's 
buffer). 
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For example, suppose you perform an Open operation, find that the value of 
XAB$W_ACLLEN is greater than the ACL buffer, and then perform Display 
operations until all of the ACEs in the ACL have been returned. You can then 
reread the entire ACL on subsequent Opens or Displays only if you set the 
value of the XAB$L_ACLCTX field to 0. 

The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


14.4 XAB$W_ACLLEN Field 

The ACL length (ACLLEN) field receives the length (in bytes) of the access 
control list for the file during an Open or a Display operation. If the file has 
no ACL, the XAB$W_^CLLEN field has a value of 0. 

If the file has an ACL that fits in the user's buffer, the value of the XAB$W_ 
ACLLEN field is equal to the number of bytes in the ACL. Even if the file's 
ACL does not fit into the user's buffer, the value of the XAB$V\L.ACLLEN 
field is still equal to the number of bytes in the ACL (not just the length of 
that portion that fits into the buffer). 

To determine the number of ACL entries that are in the user's buffer, you 
must process binary ACEs until you find an ACE with a value of 0 or until 
you come to the end of the buffer. 

The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


14.5 XAB$W_ACLSIZ Field 

The ACL buffer size (ACLSIZ) field specifies the length of the user buffer that 
contains (or will contain) binary ACEs used as input to a Create service and 
as output to an Open or Display service. 

VMS RMS passes all information, including the ACL buffer, to and from the 
file system using buffered I/O operations. VMS RMS limits buffered I/O 
transfers to 512 bytes, excluding the ACL buffer. Therefore, the size of the 
ACL buffer plus 512 bytes cannot exceed either the BYTLM quota for the 
process or the MAXBUF value for the system. 

The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


14.6 XAB$L_ACLSTS Field 

The ACL error status (ACLSTS) field contains a system error status relating 
to the processing of ACLs. A value is returned to this field upon a successful 
return from a Create, Open, or Display service. 

Whenever you use the XAB$L_ACLBUF, XAB$L_ACLCTX, XAB$W__ 
ACLLEN, or XAB$W-_ACLSIZ fields, be sure to use the following error¬ 
handling guidelines: 

• If the FAB$L_STS field (RO) contains an error status, handle the error in 
the usual manner. 
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• If the FAB$L_STS field (RO) contains a success status, then you must 
check the value in XAB$L_ACLSTS. If XAB$L_ACLSTS contains a 
success status, then the entire operation completed successfully and 
no further action is required; if XAB$L_ACLSTS contains an error 
status, handle the error appropriately. Note that a value is placed in the 
XAB$L_ACLSTS field only when a success status is returned in FAB$L_ 
STS (RO). 

This extra level of error checking is necessary because the success or failure 
of reading and writing ACLs is independent of the success or failure of the 
whole operation. Thus, in the absence of this additional error checking, it is 
possible to create a file successfully even though an ACL error occurred. 

This field is relevant only when an ACL is used with a Create service or when 
an ACL is returned from an Open or Display service. The use of this field for 
DECnet remote file access is not supported, and it is ignored during DECnet 
operations. 


14.7 XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABPRO, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_PROLEN (this is done by the $XABPRO macro). 


14.8 XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block 
as an XABPRO. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_PRO (this is done by the $XABPRO macro). 


14.9 XAB$W_GRP Field 

The file owner group number (GRP) field contains the half of the XAB$L_ 
UIC field that defines the group number. Refer to the XAB$L_UIC field 
description for additional information. The contents of the XAB$L_UIC field, 
rather than the $XABPRO macro, establish the initial value of the XAB$W_ 
GRP field. 

This field corresponds to the FDL attribute FILE OWNER. 
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14.10 XAB$W_MBM Field 

The file owner member number (MBM) field contains the half of the XAB$L__ 
UIC field that defines the member number. Refer to the XAB$L_UIC field 
description for additional information. The contents of the XAB$L_UIC field, 
rather than the $XABPRO macro, establish the initial value of the XAB$W_ 
MBM field. 

This field corresponds to the FDL attribute FILE OWNER. 


14.11 XAB$B_MTACC Field 

The magnetic tape accessibility (MTACC) field enables you to access HDRl 
labels for ANSI-labeled magnetic tapes, in compliance with ANSI standards. 
The value specified in the XAB$B_MTACC field is input to the Create service 
and output from the Open and Display services for magnetic tape only. 

The character to be inserted in the accessibility field of the HDRl label must 
be one of the following: 

• An uppercase letter from A through Z 

• A digit from 0 through 9 

(SPACE) 

! 

% 

&c 

( 

) 

♦ 

+ 

• One of the following special characters: , 

/ 

/ 

< 

> 

7 

Note that if this field is not specified or if the specification is invalid, a space 
character is inserted into the HDRl accessibility field. 

This field corresponds to the FDL attribute FILE MT_PROTECTION. and it is 
not supported for DECnet operations. 


14.12 XAB$L_NXT Field 

The next XAB address (NXT) field specifies the symbolic address of the next 
XAB in the XAB chain. A value of 0 (the default) indicates that the current 
XAB is the last (or only) XAB in the chain. 


14-5 






Protection XAB (XABPRO) 

14.13 XAB$W_PRO Field 


14.13 XAB$W_PRO Field 

The file protection (PRO) field specifies the access privileges granted to the 
four classes of users: system, owner, group, and world. 

This field consists of four 4-bit subfields; each subfield is a binary options 
field where each possible access privilege has a corresponding bit assignment. 
The file access privileges must be specified in the following order: 

<SYSTEM,OWNER,GROUP,WORLD> 

To deny access, set the appropriate bits in the protection word to 1. If you 
want to grant access to a specific user class, clear the appropriate bit. 

The following list associates each subfield with its symbolic offset: 

• System—XAB$V_SYS 

• Owner—XAB$V_OWN 

• Group—XAB$V_GRP 

• World—XAB$V_WLD 

Additionally, each access specification has the following mask values: 

• No read access—XAB$M_NOREAD 

• No write access—XAB$M_NOWRITE 

• No execute access—XAB$M_NOEXE 

• No delete access—XAB$M_NODEL 

A user is granted the maximum number of types of access rights for each of 
the classes to which he belongs. 

Each access code consists of four bits for each user class, or four subfields 
in the word identified by XAB$W_PRO. This field is organized as shown in 
Figure 14-1. 

Figure 14-1 File Protection Field 


15 12 11 8 7 4 3 0 


world 


group 


owner 


system 


ZK-872-82 


14-6 











Protection XAB (XABPRO) 

14.13 XAB$W_PRO Field 


If you do not explicitly specify file protection when you invoke the Create 
service, VMS RMS attempts to determine file protection in the following 
order: 

1 Using the protection assigned to an existing file of the same name 

2 Using the default file protection of the directory 

3 Using the process-default protection 


The following chart provides detailed descriptions of the four user classes: 


User Class 

Description 

System 

Specifies access rights for users executing under a system 

UlC, that is, users whose group number is less than the value 
for a system UlC, which is defined by the system manager 
(usually 10 or less). 

Owner 

Specifies access rights for the owner of the file. A user Is 
considered the owner of the file only if both the group and 
member number fields of the accessing process match the 
group and member number fields of the file owner's UlC 
stored with the file. 

Group 

Specifies the access rights for users whose group number 
matches the group number field of the file owner. 

World 

Specifies access rights for all users. World access Is used for 
granting access to users who are not In the system, owner, 
or group classifications. 


This field corresponds to the FDL attribute FILE PROTECTION. 


14.14 XAB$B_PROT_OPT Field 

The ACL file protection (PROT_OPT) field provides a single option, the 
XAB$V_PROPAGATE option, which is used as input during an Enter or 
a Rename operation. (During a Rename operation, the protection XAB is 
assumed to be attached to FAB2.) 

The XAB$B_PROT_OPT field is a binary options field where each file 
protection option has a corresponding bit assignment. Options are identified 
using mnemonics, and each option has its own symbolic offset and mask 
value. For example, the PROPAGATE option has a symbolic offset of 
XAB$V_-PROPAGATE and a mask value of XAB$M_PROPAGATE. 

If the XAB$V_PROPAGATE bit is set in this field during either an Enter or 
Rename operation, the file receives new security attributes when the new 
directory entry is made. These security attributes follow the same rules as 
apply during a Create operation. For example, if a lower version of a new file 
exists, the new file inherits the security attributes of the next lower version of 
the file. If the XAB$V_PROPAGATE bit is not set, the security attributes of 
the new file do not change. 

This field is not supported for DECnet operations; it is ignored. 
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14.15 XAB$L_UIC Field 

The user identification code (UIC) field combines the two XABPRO fields that 
define the UIC of the owner of a file: the XAB$W_GRP (group number) and 
XAB$W_MBM (member number) fields. Both numbers are octal numbers. 
The valid range for a group number is 0 to 37777; the valid range for a 
member number is 0 to 177777. Note that the maximum value in each case 
(37777 and 177777) is reserved for DIGITAL use only. This field corresponds 
to the FDL attribute FILE OWNER. 

The symbolic offsets for the group number field and the member number 
field respectively are XAB$W-_GRP and XAB$W--MBM. 

The total user identification field, including both the group and member 
number fields, has a symbolic offset of XAB$L__UIC. 

Note that if no file protection XAB is provided or if the user identification 
field is null for a Create service, VMS RMS determines the owner's UIC using 
the following logical order: 

1 The owner UIC of an existing version of the file if the creating process 
has ownership rights to the previous version. 

2 The owner UIC of the parent directory, if the creating process has 
ownership privileges to the parent directory. 

3 The UIC of the creating process. 

If you wish to create an output file with a UIC different from your own, you 
must have system privilege (SYSPRV). 
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1 5 Revision Date and Time XAB(XABRDT) 


The revision date and time XAB (XABRDT) specifies the revision date and 
time and the revision number when a Close service is invoked for a file. The 
XABRDT operates much like the Date and Time XAB (XABDAT) when input 
to the Create, Open, or Display services. However, when you gain access to 
a file for writing, issuing a Close service for that file causes the revision date 
and time to be set from the current date and time and the revision number to 
be incremented. Thus, any revision date and time value you specify through 
the XAB on a Create service is lost. 

You can input the XABRDT to a Close service and cause the file's revision 
date and time and revision number to take on the specified values. If you 
want to change the revision date and time when you close the file, you must 
have write access to the file and have accessed the file for some type of 
modification (Put, Update, Delete, or Truncate). 


15.1 Summary of Fields 

The two XABRDT fields that specify revision information are described below. 

• Revision date and time (XAB$Q_RDT) is a 64-bit binary field that 
indicates the date and time at which the file was last updated. 

• Revision number (XAB$W_RVN) indicates how many times this file has 
been opened for write operations. 

The following list describes how these two XABRDT fields are used by the 
VMS RMS file-processing services. 


Service 

XAB$Q RDT 

XAB$W_RVN 

Close 

Input 

Input 


Create 

Input 

Input 


Display 

Output 

Output 


Erase 

Not used 

Not used 

Extend 

Not used 

Not used 

Open 

Output 

Outpul 



If you specify a revision date and time of 0, VMS RMS substitutes the current 
date and time when you close the file. If the XABRDT is present when you 
invoke an Open (or a Display) service, the XAB$Q_RDT field contains the 
file's revision date and time value. Because the XAB$Q_RDT field is filled 
(not 0), VMS RMS does not substitute the current date and time. 

Use the XABRDT block only to specify a new (nondefault) value for the 
XAB$Q_RDT and XAB$W_RVN fields. You must set these fields between 
the time you invoke the Open service and the time you invoke the Close 
service. If you set the XAB$Q_RDT and XAB$W_RVN fields before you 
invoke the Open service, the file's revision date, time and number override 
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the specified values. To determine the contents of the XAB$Q_RDT and 
XAB$W_RVN fields, examine the appropriate fields of the XABDAT block. 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABRDT field are presented in Table 15-1. 


Table 15-1 XABRDT Fields 


Field Offset 

Size 

(Bytes) 

FDL Equivalent 

Description 

XAB$B_BLN' 

1 

None 

Block length 

XAB$B_COD’ 

1 

None 

Type code 

XAB$L_NXT 

4 

None 

Next XAB address 

XAB$Q_RDT2 

8 

DATE REVISION 

Revision date and time 

XAB$W_RVN2 

2 

FILE REVISION 

Revision number 


^This field is statically Initialized by the $XABRDT macro to identify this control block as a 
XABRDT. 

^This field cannot be initialized by the $XABRDT macro; it must be specified before you 
invoke the Close service to be used as Input to the Close service. 


Each XABRDT field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual, 

The format and arguments of the $XABRDT and $XABRDT_STORE services 
are defined in Appendix B. 


15.2 XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABRDT, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field is initialized to the symbolic value 
XAB$C_RDTLEN by the $XABRDT macro. 


15.3 XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block as 
an XABRDT. Once set, this field must not be altered unless the control block 
is no longer needed. This field is initialized to the symbolic value XAB$C_ 
RDT by the $XABRDT macro. 


15.4 XAB$L_NXT Field 

The next XAB address (NXT) field contains the symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 
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15.5 XAB$Q_RDT Field 

The revision date and time (RDT) field contains a 64-bit binary value 
expressing the date and time at which the file was last updated. Note that 
this field is limited to a granularity of 1 second for remote files. 

This field corresponds to the FDL attribute DATE REVISION. 


15.6 XAB$W_RVN Field 

The revision number (RVN) field contains a numeric value that indicates the 
number of times this file was opened for write operations. 

This field corresponds to the FDL attribute FILE REVISION. 
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1 0 Recovery Unit XAB(XABRU) 


The recovery unit XAB ($XABRU) control block supports the use of recovery 
units to assure data file integrity. See the VAX RMS Journaling Manual for 
details. 













17 SummaryXAB(XABSUM) 



The summary XAB (XABSUM) can be associated with a FAB at the time a 
Create, Open, or Display service is invoked. The presence of this XAB during 
these calls allows VMS RMS to return to your program the total number of 
keys and allocation areas defined and the version number when the file was 
created. Note that an XABSUM is used only with indexed files. 


17.1 


Summary of Fields 

The symbolic offset, size, and a brief description of each XABSUM field are 
presented in Table 17-1. 


Table 17-1 XABSUM Fields 


Field Offset 

Size 

Description 


XAB$B_BLN’ 

Byte 

Block length 


XAB$B_COD’ 

Byte 

Type code 


XAB$B_NOA^ 

Byte 

Number of allocation areas defined for the file 

XAB$B_N0K2 

Byte 

Numbers of keys 

defined for the file 

XAB$L_NXT 

Longword 

Next XAB addres: 

s 

xab$w_pvn2 

Word 

Prolog version number 


^This field is statically initialized by the SXABSUM macro to identify this control block as 
an XABSUM. 

^This field cannot be Initialized by the $XABSUM macro. 


Each XABSUM field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VMS Version 5.0 
systems. See the VMS Networking Manual for information about the support 
of VMS RMS options for remote file access to other systems. 

The format and arguments of the $XABSUM and $XABSUM—STORE macros 
are defined in Appendix B. 


17.2 XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABSUM, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field is initialized to the symbolic value 
XAB$C_SUMLEN by the $XABSUM macro. 
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17.3 XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block as 
an XABSUM. Once set, this field must not be altered unless the control block 
is no longer needed. This field is initialized to the symbolic value XAB$C_ 
SUM by the $XABSUM macro. 


17.4 XAB$B_NOA Field 

The number of allocation areas (NOA) field indicates the number of allocation 
areas defined when the file was created. Refer to Chapter 8 for information 
about multiple allocation areas. 


17.5 XAB$B_NOK Field 

The number of keys (NOK) field indicates the number of keys defined when 
the file was created. Refer to Chapter 13 for more information. 


17.6 XAB$L_NXT Field 

The next XAB address (NXT) field contains the symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 


17.7 XAB$W_PVN Field 

The prolog version number (PVN) contains a numeric value that indicates 
the prolog number defined when the file was created. For more information 
about prolog numbers, refer to Chapter 13. 








'I 8 Terminal XAB (XABTRM) 


The terminal XAB (XABTRM) allows extended terminal read operations to 
occur when a VMS RMS Get service is used for a terminal device. Unlike 
most other XABs, the XABTRM is associated with a RAB (record stream). The 
XABTRM provides information that VMS RMS passes to the terminal driver 
to process a user-defined item list that defines the terminal read operation. 


18.1 Summary of Fields 

The symbolic offset, size, and a brief description of each XABTRM field are 
presented in Table 18-1. 


Table 18-1 XABTRM Fields 


Field Offset 

Size 

(Bytes) 

Description 

XAB$B_BLN’ 

1 

Block length 

XAB$B_COD’ 

1 

Type code 

XAB$L_ITMLST 

4 

Item list address 

XAB$W_1TMLST_LEN 

2 

Item list length 

XAB$L_NXT 

4 

Next XAB address 

^This field is statically initialized by the $XABTRM macro to identify this control block as 
an XABTRM. 


To perform the extended terminal read operation, the following information 

is required: 

• In the RAB, the RAB$L_ROP field RAB$V_ETO option must be specified 
(set). 

• In the RAB, the RAB$L_XAB field must contain the address of the 
XABTRM. 

• In the XABTRM, the XAB$L_ITMLST and XAB$W_ITMLST_LEN fields 
must contain the starting address and length of a valid terminal driver 
read function item list. 

• The item list must be supplied according to the conventions described 
for creating an item list for the terminal driver in the VMS I/O User's 
Reference Manual: Part I in the VMS I/O User's Reference Volume. 

An item list consists of one or more item list entries, where each item 
defines an attribute of the terminal read operation. Instead of defining 
terminal read arguments in the RAB, all such arguments (including certain 
arguments only available with the item list method) are defined in the 
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18.1 Summary of Fields 


item list. The following list shows the RAB$L_ROP options related to a 
terminal read operation and the equivalent item codes: 


RAB$L_ROP 

Bit Offset Item Code 

RAB$V_CVT TRM$_MODIFIERS, bit TRM$M_TM_CVTLOW 

RAB$V_PMT TRM$_PROMPT 

RAB$V_PTA TRM$_MODIFIERS, bit TRM$M_TM_PURGE 

RAB$V_RNE TRM$_MODIFIERS, bit TRM$M_TM_NOECHO 

RAB$V_RNF TRM$_MODIFIERS, bit TRM$M_TI\/l_NOFILTR 

RAB$V TMO TRM$TIMEOUT 


Each item code required for the terminal read operation is placed in an 
item list along with other required information. Each item code is made 
up of three longwords. Note that VMS RMS does not validate the item 
list. If the item list is invalid, VMS RMS returns RMS$_QIO status in 
the RAB$L _STS field and the specific terminal driver QIO status in the 
RAB$L _STV field (see the VMS I/O User’s Reference Manual: Part I in 
the VMS I/O User's Reference Volume). 

Each XABTRM field is described below. The XABTRM is not supported for 
DECnet operations between two VMS systems. Thus, access to XABTRM 
fields for DECnet operations is not supported. There are no equivalent FDL 
attributes for the XABTRM fields. 

The format and arguments of the $XABTRM macro and the $XABTRM_ 
STORE macro are defined in Appendix B. 


18.2 XAB$B_BLN Field 

The block length (BLN) field is a static field that defines the length of the 
XABTRM, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field is initialized to the symbolic value 
XAB$C_TRMLEN by the $XABTRM macro. 


18.3 XAB$B_COD Field 

The type code (COD) field is a static field that identifies this control block as 
an XABTRM. Once set, this field must not be altered unless the control block 
is no longer needed. This field is initialized to the symbolic value XAB$C_ 
TRM by the $XABTRM macro. 


18.4 XAB$L_ITMLST Field 

The item list address (ITMLST) field contains the symbolic address of the item 
list that defines the extended terminal read operation. 


18-2 










Terminal XAB (XABTRM) 

18.5 XAB$W_ITMLST_LEN Field 


18.5 XAB$W_ITMLST_LEN Field 

The item list length (ITMLST_LEN) field contains a numeric value that 
indicates the length of the item list, in bytes. 


18.6 XAB$L_NXT Field 

The next XAB address (NXT) field contains the symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 
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VMS RMS Services 

Part III, VMS RMS Services, lists the format of each VMS RMS service and 
describes each service in detail. Each VMS RMS service is documented in 
a structured format. See the Introduction to VMS System Routines for a 
discussion of the format and how it is used. 

Note that the calling format for each service requires a place holder (a 
comma) if you omit the first optional argument (err) but include the second 
optional argument (sue). 
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$CLOSE 


$CLOSE 

The Close service terminates file processing and closes the file. This 
service performs an implicit Disconnect service for all record streams 
associated with the file. 

FORMAT 

S YS$C LOS E fab [,[err] [, sue]] 


RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 


ARGUMENTS 


fab 

VMS usage: 
type: 
access: 
mechanism: 


fab 

longword (unsigned) 

modify 

by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Close service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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$CLOSE 


DESCRIPTION 


You can invoke the Close service only when no operation is currently under 
way (by your process) for the file being processed; that is, when no VMS 
RMS requests for the file are outstanding. When this condition is satisfied, 
the file can be closed to set the internal file identifier field to 0. 

When the Close service is invoked properly, VMS RMS disconnects all RABs 
for you, performs the various cleanup procedures (including file option 
processing and XAB processing), and closes the file. The only types of XABs 
that the Close service processes are the file protection XAB (XABPRO) and 
revision date and time XAB (XABRDT). It processes these XABs only if the file 
was opened or created for write access. 

If a process tries to implement the truncate service when closing a secjuential 
file, it must have sole write access to the file. If other processes have write 
access to the file, it remains accessible until all processes have completed. 

If other processes have the file open for read access, VMS RMS defers the 
truncation until the final process having read access closes the file. 

Table RMS-1 lists the control block fields read as input by the Close service. 
Note that if the FAB$V_DLT, FAB$V_SCF, or the FAB$V_SPL bits are set 
by the associated Open or Create service, VMS RMS does not act on them 
for the Close service. For example, if you open the file and specify that it be 
deleted on close by setting the FAB$V_DLT bit, the file is deleted by VMS 
RMS when it is closed regardless of the bit's state when the Close service is 
invoked. 

For additional information on the fields accessed by this service, see Part II. 


Table RMS-1 

Close Service FAB and XAB Input Fields 

Field Name 

Option or 

XAB Type 

Description 

FAB$W_IFI’ 


Internal file identifier. 

FAB$L_FOP 


File-processing options. 


FAB$V_DLT 

Deletes file on close. 


FAB$V_RWC 

Rewinds a magnetic tape volume. 


FAB$V_SCF2 

Submits a file as a batch job (sequential files 


FAB$V_SPL2 

only). 

Submits a file to the print queue (sequential 


FAB$V_TEF 

files only). 

Truncates data at the end of the file 

FAB$L_XAB 


(sequential files only). 

Next XAB address. 


XABPRO 

Modifies file protection and ownership. 


XABRDT 

Modifies revision date and number. 


'This field is required input to the FAB. 

^This field is not supported for DECnet operations. 


Table RMS-2 lists the control block fields written as output by the Close 
service. 
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RETURN 

VALUES 


VMS RMS Services 

$CLOSE 


Table RMS-2 Close Service FAB and XAB Output Fields 


Field Name 

Option or 
XAB Type 

Description 

FAB$W_IFI 


Internal file identifier (cleared). 

FAB$L_STS 


Completion status (also returned in register 0). 

FAB$L_STV 


Status value. 

FAB$L_XAB 


Next XAB address. 


XABRDT 

New revision date and number returned. 


The following condition values are described in Appendix A; 


RMS$_ACT 

RMS$_BUG_DAP 

RMS$_COD 

RMS$_DNR 

RMS$_IMX 

RMS$_NORMAL 

RMS$_SUC 

RMS$_WBE 

RMS$_XAB 


RMS$_ATR 

RMS$_BUSY 

RMS$_CRC 

RMS$_EXENQLM 

RMS$_MKD 

RMS$_PRV 

RMS$_SUP 

RMS$_WER 


RMS$_ATW 

RMS$_CCF 

RMS$_DAC 

RMS$_FAB 

RMS$_NET 

RMS$_SPL 

RMS$_SUPPORT 

RMS$_WLK 


RMS$_BLN 

RMS$_CDA 

RMS$_DME 

RMS$_IFI 

RMS$_NETFAIL 

RMS$_STR 

RMS$_SYS 

RMS$_WPL 


Note that even though a failure is indicated by the completion status code 
value, the file is closed if VMS RMS clears the internal file identifier value 
(FAB$W_1FI). 
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$CONNECT 


$CONNECT 


The Connect service establishes a record stream by associating and 
connecting a RAB with a FAB. You can invoke the Connect service only 
for files that are already open. 


FORMAT SYS$CONNECT rab [Jerr][,suc]] 


RETURNS 


VMS usage: 
type; 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 


ARGUMENTS 


tab 

VMS usage; 
type: 
access; 
mechanism: 


rab 

longword (unsigned) 

modify 

by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Connect service call. The rab argument is the address of the RAB control 
block. 


err 


VMS usage; 
type: 
access: 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the Connect service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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SCONNECT 


Any number of RABs can be connected to a FAB if the multistream (FAB$V_ 
MSE) option is selected when the file is opened or created. Each RAB 
represents an independent record stream. 

When you issue a Connect service, VMS RMS allocates an internal 
counterpart for the RAB. This counterpart consists of the internal controls 
needed to support the stream, such as record pointers and request status 
information. All required I/O buffers are also allocated at this time. 

The Connect service also initializes the next record pointer to the first record. 
In indexed files, the key of reference establishes the index of the next record 
pointer. 

If you set the end-of-file (RAB$V_EOF) option in the RAB$L_ROP field 
when issuing a Connect service, VMS RMS examines the organization of the 
file being processed to determine the end-of-file positioning strategy. 

For sequential or relative files, VMS RMS goes to the next record beyond the 
last currently existing record in the file. (The next record is inserted at the 
logical end of the file, and the service returns RMS$_EOF status in response 
to a request for sequential access.) 

For indexed files, VMS RMS verifies that the first record inserted is inserted in 
the proper sort order. If the record cannot be inserted in the proper sort order 
because of user action, VMS RMS returns a sequence error (RMS$_SEQ). 

Get services that specify the sequential record access mode (RAB$B_RAC 
is RAB$C_SEQ) return an RMS$_EOF status. Get services that specify the 
random access mode (RAB$B_RAC is RAB$C_KEY), ignore (turn off) the 
end-of-file positioning. Positioning to end-of-file is supported for all indexed 
files, regardless of how many indexes the file contains. However, the EOF 
positioning is supported only when you access a file by the primary key. If 
the specified key of reference is a secondary key, an RMS$_ROP message is 
returned. 

In most cases, setting the RAB$V_EOF bit guarantees that the next record is 
inserted at the logical end of the file. However, if a relative file or an indexed 
file is shared by two or more active processes, the following scenario may 
develop. 

Assume that process A has invoked the Connect service after setting the 
RAB$V_EOF bit and is positioned to the end of the file. Before process A can 
do a $PUT, process B inserts a record into the file and changes the current 
record position. When process A attempts to do a $PUT into the position 
that was formerly the end of the file, the record may be inserted improperly. 
It may be inserted either before or after the record inserted by process B, 
depending on the respective key values. Or, the $PUT operation may even 
fail if the keys have the same value and duplicates are not allowed. 

Table RMS-3 lists the control block fields read as input by the Connect 
service. For additional information about the fields accessed by this service, 
see Part II. 
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Table RMS-3 Connect Service RAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

RAB$L_FAB' 


File access block address (required to access 
the internal file identifier field, FAB$W_IFI). 

RAB$W_ISI’ 


Internal stream identifier (must be 0). 

RAB$B_KRF 


Key of reference (applies only to Indexed 
files). 

RAB$B_MBC2 


Multiblock count (applies only to sequential 
files residing on disk devices). 

RAB$B_MBF2 


Multibuffer count. 

RAB$L_ROP 


Record-processing options: 


RAB$V_ASY 

Asynchronous: performs Connect service 
asynchronously. 


RAB$V_BIO 

Block I/O: specifies that only block I/O 
operations are permitted. The FAB$B_FAC 
field FAB$V_BRO or FAB$V_BIO option must 
be specified to the Open or Create service. 


RAB$V_EOF^ 

End-of-file: positions to the end of the file 
upon execution of the Connect service. 


RAB$V_RAH2 

Read ahead: allocates at least two buffers 
for multibuffering (applies only to sequential 
files on disk devices). 


RAB$V_WBH2 

Write behind: allocates at least two buffers 
for multibuffering (applies only to sequential 
files on disk devices). 


^This field is a required input to the Connect service. 


^This field Is not supported for DECnet operations. 
^Refer to text for exceptions. 


Table RMS-4 lists the control block fields written as output by the Connect 
service. 

Table RMS-4 

Connect Service RAB Output Fields 

Field 

Name 

Description 

RAB$W_ISI 

RAB$L_STS 

RAB$L_STV 

Internal stream identifier. 

Comipletion status code (also returned in Register 0). 

Status value. 
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RETURN The following condition values are described in Appendix A: 


VALUES 

RMS$_ACT 

RMS$_BLN 

RMS$_BUG_DAP 

RMS$_CCR 


RMS$_CDA 

RMS$_CRMP 

RMS$_DME 

RMS$_FAB 


RMS$_GBC 

RMS$_IAL 

RMS$_IFA 

RMS$_IFI 


RMS$_KRF 

RMS$_MBC 

RMS$_NET 

RMS$_NETFAIL 


RMS$_NORMAL 

RMS$_PENDING 

RMS$_RAB 

RMS$_RFM 


RMS$_ROP 

RMS$_SUP 

RMS$_RPL 

RMS$_SUPPORT 

RMS$_STR 

RMS$_SUC 
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$CREATE 


The Create service constructs a new file according to the attributes 
you specify in the FAB. If any XABs are chained to the FAB, then the 
characteristics described in the XABs are applied to the file. This service 
performs implicit Open and Display services. 


FORMAT SYS$CREATE fab [,[err] [,suc]] 


RETURNS 


VMS usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 


ARGUMENTS 


fab 

VMS usage: 
type: 
access: 
mechanism: 


fab 

longword (unsigned) 

modify 

by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Create service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


The Create service first uses the information from the specified FAB. If an 
allocation control XAB is present, however, its allocation quantity (XAB$L_ 
ALQ), allocation options (XAB$B_AOP, only for the XAB$V_CTG and 
XAB$V_CBT options), bucket size (XAB$B_BKZ), and default extension 
quantity (XAB$W_DEQ) fields are used instead of the corresponding fields 
of the FAB. When either key definition or allocation XABs are present, they 
can be grouped in any order. If a name block (NAM) is also connected to the 
FAB, VMS RMS fills in its fields with information about the created file. The 
Create service leaves the file opened. 

When a search list logical name is used, the file is placed in the first resultant 
search list file specification unless the create-if (FAB$V-_CIF) option is 
specified. If you select the FAB$V_CIF option, VMS RMS searches all search 
list file specifications to locate the file. If it finds the file, VMS RMS opens it 
rather than create a new file. If VMS RMS does not find the file, it creates a 
new file using the first resultant search list file specification. 

You do not have to explicitly specify the FAB$V__PUT option when invoking 
a Create service because write is the default access mode when you create a 
file. 

Table RMS-5 lists the control block fields read as input by the Create service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-5 Create Service FAB and XAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

FAB$L_ALQ 


Allocation quantity; ignored if an 
allocation XAB is present. 

FAB$B_BKS 


Bucket size; ignored if an allocation XAB 
is present. 

FAB$W_BLS 


Block size (applies to magnetic tape 
only). 

FAB$W_DEQ 


Default file extension quantity; ignored if 
an allocation XAB is present. 

FAB$L_DNA 


Default file specification string address. 

FAB$B_DNS 


Default file specification string size. 

FAB$B_FAC 


File access. 


FAB$V_BIO 

Block I/O access to file. 


FAB$V_BRO 

Block or record I/O access to file. 


FAB$V_DEL 

Delete access to file. 


FAB$V_GET’ 

Read access to file. 


FAB$V_PUT’ 

Write access to file and explicit file 
extension. 


FAB$V_TRN 

Truncate access to file. 


FAB$V_UPD 

Update access to file and explicit file 
extension. 

’These are the default values supplied by VMS RMS. 
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Table RMS-5 (Coht.) Create Service FAB and XAB input Fields 


Field Name 

Option or 

XAB Type 

Description 

FAB$L_FNA2 


File specification string address. 

FAB$B_FNS^ 


File specification string size. 

FAB$L_FOP 


File-processing options. 


FAB$V_CBT 

Contiguous best try: indicates that the 
file is to be allocated contiguously on 
a "best effort" basis. If VMS RMS is 
unable to allocate the file within three 
extents, this bit is switched off by the 
Create service. To specify a single 
extent, use the FAB$V_CTG option. 


FAB$V_CIF 

Create-if: opens a file if it already exists 
or creates a file if it does not already 
exist. 


FAB$V_CTG 

Contiguous: indicates that the space for 
a file is to be allocated contiguously. 

FAB$V_CHAN_ 

MODE^ 


Assigns the channel access mode. 


FAB$V_DFW3 

Deferred write: writing back to the file 
from the modified buffer is deferred. 
Applies to relative and Indexed files 
and sequential files opened for shared 
access. 


FAB$V_DLT 

Delete: indicates that the file is to be 
deleted when closed. 

FAB$V_LNM_ 


Specifies the logical name translation 

MODE^ 


access mode. 


FAB$V_MXV 

Maximize version: Indicates that the 
created file be given the specific version 
number requested or a version number 
that is one greater than the highest 
version number of an existing file. 


FAB$V_NAM^ 

Name block inputs: indicates that the 
NAM$W_DID and NAM$T_DVI fields 
in the specified NAM block are used as 
input. 


FAB$V_NFS^ 

Non-flie-structured: Indicates that the 
accessed volume Is to be processed in a 
non-file-structured manner. 


FAB$V_OFP 

Output file parse: specifies that the 
resultant file specification string of the 
related file. If used, is to provide file 
name and file type defaults only. 


^These fields must be specified unless you select the FAB$V_TMD or the FAB$V_TMP 
option. 


^This field is not supported for DECnet operations. 
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$CREATE 

Table RMS- 

-5 (Cent.) Create Service FAB and XAB Input Fields 


Option or 


Field Name 

XAB Type 

Description 


FAB$V_POS 

Current position (applies to magnetic 
tapes only). 


FAB$V_RCK 

Read-check: Indicates that transfers 
from disk are to be followed by a 
read-compare operation. 


FAB$V_RWC 

Rewind on close (applies to magnetic 
tape only). 


FAB$V_RWO 

Rewind on open (applies to magnetic 
tape only). 


FAB$V_SCF 

Submit command file: indicates that 
the file Is to be submitted as a batch- 
command file to the process default 
batch queue (SYS$BATCH) when the file 
is closed (applies to sequential files only). 


FAB$V_SPL 

Spool: Indicates that the file Is to be 
spooled to the process default print 
queue (SYS$PRINT) when the file is 
closed (applies to sequential files only). 


FAB$V_SQO 

Sequential only: indicates that the file 
can be processed In a sequential manner 
only, usually to enable DECnet-VAX file 
transfer. 


FAB$V_SUP 

Supersede: allows an existing file to be 
superseded by a new file of the same 
name, type, and version. 


FAB$V_TEF 

Truncate at end of file: Indicates that 
the unused space allocated to a file 
is deallocated when that file is closed 
(applies to sequential files only). 


FAB$V_TMD 

Temporary marked for delete: Indicates 
that a temporary file Is to be created, 
and then deleted when the file is closed. 


FAB$V_TMP 

Temporary: Indicates that a temporary 
file is to be created and retained, but no 
directory entry Is made for this file. 


FAB$V_UFO^ 

User file open: indicates that the file is 
to be created or opened only (no further 
processing of that file by VMS RMS is 
allowed). 


FAB$V_WCK 

Write-check: indicates that transfers 
to disk are to be followed by a read- 
compare operation. 

FAB$B_FSZ 


Fixed control area size. 

FAB$W_GBC 

3 

Global buffer count for shared files. 

^This field is not supported for DECnet operations. 
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Table RMS-5 (Coijit.) Create Service FAB and XAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

FAB$W_IFI 


Internal file identifier (must be 0). 

FAB$L_MRN 


Maximum record number (applies to 
relative files and sequential files having 
fixed-length 512-byte records). 

FAB$W_MRS 


Maximum record size. 

FAB$L_NAM 


Name block address. 

FAB$B_ORG 


File organization: sequential (FAB$C_ 
SEQ^), relative (FAB$C_REL), or indexed 
(FAB$C_IDX). 

FAB$B_RAT 


Record attributes. 

FAB$B_RFM 


Record format: fixed-length (FAB$C_ 
FIX), variable-length (FAB$C_VAR), 

VFC (FAB$C_VFC), stream (FAB$C_ 
STM), stream with line feed terminator 
(FAB$C_STMLF), stream with carriage 
return terminator (FAB$C_STMCR), or 
unidentified format (FAB$C_UDF^). 

FAB$B_RTV^ 


Retrieval window size. 

FAB$B_SHR 


File sharing. 


FAB$V_SHRDEL 

Allows other users to delete records 
from the file. 


FAB$V_SHRGET 

Allows other users to read the file; also 
used with the FAB$V_MSE and FAB$V_ 
GET bits to specify a read-only global 
buffer cache when global buffering is 
enabled. 


FAB$V_MSE^ 

Allows multistream access. 


FAB$V_NIL 

Prohibits any type of file sharing by other 
users. 


FAB$V_SHRPUT 

Allows other users to write records to 
the file and extend it. 


FAB$V_SHRUPD 

Allows other users to update records in 
the file and extend it. 


FAB$V_UPI 

Allows one or more users write access 
to a shared file open for block I/O 
(applies to sequential files only). 

FAB$L_XAB 


Extended attribute block address. 


XABALL 

Allocation XAB; see Chapter 8. 


XABDAT 

Date and time XAB; see Chapter 9. 


XABFHC 

File header characteristics XAB; see 
Chapter 10. 


’These are the default values supplied by VMS RMS. 
^This field is not supported for DECnet operations. 
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Table RMS- 

5 (Cent.) Create Service FAB 

and XAB Input Fields 


Option or 



Field Name 

XAB Type 

Description 


XABITM 

Item list XAB; see Chapter 11. 


XABKEY 

Key definition XAB; see Chapter 13. 


XABPRO 

Protection 

XAB; see Chapter 14. 


XABRDT 

Revision date and time XAB; see 



Chapter 1E 



XABSUM 

Summary XAB; see Chapter 17. 

Table RMS-6 lists the control block fields written as output by the Create 

service. 




Table RMS- 

'6 Create Service FAB and XAB Output Fields 


Option or 



Field Name 

XAB Type 

Description 


FAB$L_ALQ 


Allocation quantity: contains actual number 



of blocks allocated. 

FAB$B_BKS 


Bucket size: 

applies only to relative and 



indexed files. 

When multiple areas are 



defined for an indexed file, the largest 



bucket size is 

; returned. 

FAB$W_BLS 


Device block 

size (applies to files of 



sequential organization only). 

FAB$W_DEQ 


Default file extension quantity. 

FAB$L_DEV 


Device characteristics. 

FAB$B_FAC 


File access. 


FAB$L_FOP 


File-processing option. 


FAB$V_CBT 

If this bit is set on input and remains on 



as output, it 

indicates that the file was 



allocated within three extents. 

FAB$B_FSZ 


Fixed-length i 

control area size for VFC 



format. 


FAB$W_GBC 


Global buffer 

count. 

FAB$W_IFI 


Internal file identifier. 

FAB$L_MRN 


Maximum record number. 

FAB$W_MRS 


Maximum record size. 

FAB$B_ORG 


File organization. 

FAB$B_RAT 


Record attributes. 

FAB$B_RFM 


Record forma 

It. 

FAB$L_SDC 


Secondary device characteristics. 

FAB$B_SHR 


File sharing. 
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Table RMS-6 (Cont.) Create Service FAB and XAB Output Fields 


Option or 

Field Name XAB Type Description 


FAB$L_STS 


Completion status code (also returned in 
register 0). 

FAB$L_STV 


Status value: contains the I/O channel 
number if the operation Is successful. 

FAB$L_XAB 


Next XAB field. 


XABALL 

Allocation XAB; see Chapter 8. 


XABDAT 

Date and time XAB; see Chapter 9. 


XABFHC 

File header characteristics XAB; see 

Chapter 10. 


XABITM 

Item list XAB; see Chapter 11. 


XABKEY 

Key definition XAB; see Chapter 13. 


XABPRO 

Protection XAB; see Chapter 14. 


XABRDT 

Revision date and time XAB; see 

Chapter 15. 


XABSUM 

Summary XAB; see Chapter 17. 


Use of the NAM Block for Creating Files 

Table RMS~7 and Table RMS-8 list the NAM block fields that VMS RMS 
uses as input and output for the Create service (provided that the name block 
address field (FAB$L_NAM) is specified). 


Table RMS-7 Create Service NAM Block Input Fields 


Field Name 

Option 

Description. 

NAM$W_DID' 



Directory Identification (Input only if 
the FAB$L_FOP FAB$V_NAM option 
is set). 

NAM$T_DVl’ 



Device identification (input only if the 
FAB$L_FOP FAB$V_NAM option Is 
set). 

NAM$L_ESA 



Expanded string area address. 

NAM$B_ESS 



Expanded string area size. 

NAM$B_NOP 



NAM block options. 


NAM$V_PWD 

Password: Indicates that a password 


contained in a DECnet access control 
string, if present in a file specification, 
is to be left unaltered in the expanded 
and resultant strings (instead of being 
replaced by the word "password"). 


^This field is not supported for DECnet operations. 
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Table RMS-7 (Cent.) Create Service NAM Block Input Fields 


Field Name 

Option Description. 


NAM$V_NOCONCEAL Do not conceal device name: indicates 
that when a concealed device logical 
name is present, the concealed device 
logical name Is to be replaced by the 
actual physical device name in the 
resultant string. 

NAM$L_RLF 

Related file NAM block address. 

NAM$L_RSA Related file NAM block resultant string 

address. 

NAM$B_RSL Related file NAM block resultant string 

length. 

NAM$L_FNB Related file NAM block file name 

status bits. 

NAM$L_RSA 

Resultant string area address. 

NAM$B_RSS 

Resultant string area size. 

Table RMS-8 

Create Service NAM Block Output Fields 

Field Name 

Description 

NAM$W_DID' 

Directory identification. 

NAM$T_DVr 

Device identification. 

NAM$B_ESL 

Expanded string length. If the NAM$I_ESA field and the 

NAM$B_ESS field are nonzero, and you do not select the 
FAB$V_NAM option, or If the NAM$W_DID field Is clear when 
you invoke the Create service, VMS RMS copies the expanded 

file specification string to the buffer specified by the NAM$I_ 

ESA field. 

NAM$W_FID’ 

File identification. 

NAM$L_FNB 

File name status bits. This is an output field from the Create 
service only If the NAM bit in FAB$L_FOP field is clear, or if 
the NAM$W_DID field is clear when you invoke the Create 
service. 

NAM$B_RSL 

Resultant string length. If the NAM$L_RSA field and the 
NAM$B_RSS field are both nonzero on input, the resultant file 
specification Is copied to the buffer specified by NAM$I_RSA. 

^This field is not supported for DECnet operations. 


Creating Files with the Create-lf Option 

Note that setting the create-if (FAB$V_CIF) option in the FAB$L_FOP field 
specifies that if a new file has the same file specification as an existing file, 
VMS RMS opens the existing file and no new file is created. Some fields 
in the FAB, such as the file organization (FAB$B_ORG) and record format 
(FAB$B_RFM) fields, are input to a Create service, but are output from an 
Open service. For example, the indexed file organization could be specified 
in the FAB$B_ORG field on a create-if operation. However, if an existing 
sequential file has the same file specification as the indexed file that the user 
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is attempting to create, then the existing file is opened and the FAB$B—ORG 
field is set to sequential. 

Creating Indexed Piles 

An indexed file consijsts of a prolog, with which it begins, and one or more 
index structures. VMS RMS supplies the prolog with certain information 
about the file, including file attributes. 


VMS RMS supports two prolog levels, called Prolog 2 and Prolog 3. Unlike 
Prolog 2 files, Prolog! 3 files allow for file compression and additional key 
types. For compatibility with RMS-11 data files that are transported or copied 
(without conversion) between systems, you may want to choose Prolog 2. 


If you want to createj a Prolog 3 file, you must be sure that records in the 
file are not larger thain 32,224 bytes and, if the primary key is segmented, 
that the segments of the primary key do not overlap (one or more bytes of 
the record are used ih more than one segment). If the primary key contains 
overlapping segments, you can consider using that key as an alternate key 
instead of a primary jkey or you can request (or let VMS RMS assign you) a 
Prolog 2 indexed file. 


Prolog 3 is the default prolog for VMS RMS, although VMS RMS creates a 
Prolog 2 file only if tlie key characteristics are not compatible with Prolog 3 
files. You can, however, override this default by requesting a specific prolog 
version. The option you choose in requesting a specific prolog level affects 
the behavior of VMS RMS with regard to creating the file and returning error 
messages. ! 


If you explicitly requjest a prolog version using the XABKEY XAB$B_ 
PROLOG field in an application program, and if other file characteristics 
are incompatible witlji that prolog, then VMS RMS returns an error message 
and does not attempi| to create the file. For example, if you explicitly specify 
Prolog 2 in the XAB$B_PROLOG field and have requested a key type that is 
available only with Ffrolog 3 (such as an 8-byte integer key type), an error is 
returned and the file is not created. 

However, if a specific! prolog version is not explicitly requested in the XAB$B_ 
PROLOG field, VMS RMS selects the greatest prolog level that can support 
the specified key characteristics and does not return an error completion code. 

In summary, there arte two ways in which you can specify a particular prolog 
version: 


• Specify the XAB$B_PROLOG field in an XABKEY block in an application 
program, affecting only the file being created. 

• Use the DCL coirmiand SET RMS_DEFAULT/PROLOG to change the 
process default. 


If you do not specify; the XAB$B_PROLOG field in your application program, 
VMS RMS examines lyour process defaults to check for prolog information. If 
this information is ncit specified in your process defaults, VMS RMS examines 
the system defaults. [If no prolog information is specified at the system level, 
VMS RMS attempts tjo create a Prolog 3 file. 


RMS-18 









VMS RMS Services 

$CREATE 


RETURN 

VALUES 


You need not be concerned with the distinctions between Prolog 2 and Prolog 
1 files. To create an indexed file with a prolog version other than Prolog 
3, specify a Prolog 2 file. If all keys in the file are string keys, VMS RMS 
provides a default of Prolog 1; in all other cases, Prolog 2 is the default. If 
the file contains all string keys and Prolog 2 is requested, VMS RMS attempts 
to create a Prolog 1 file only if no binary keys are present. 


Note that RMS-11 and previous versions of VMS RMS return error messages 
if requested to process Prolog 3 files. 


If a failure is indicated, the file may be created, but it may not be opened for 
processing, depending on the nature of the failure. 


The following condition values are described in Appendix A: 


RMS$_ACS 

RMS$_ALN 

RMS$_ATR 

RMS$_BKZ 

RMS$_BUG_DAP 

RMS$_CHN 

RMS$_CREATED 

RMS$_DAN 

RMS$_DIR 

RMS$_DNF 

RMS$_DVI 

RMS$_ESA 

RMS$_EXP 

RMS$_FLG 

RMS$_FNF 

RMS$_FSZ 

RMS$_IAL 

RMS$_IFA 

RMS$_IMX 

RMS$_KSI 

RMS$_MRN 

RMS$_NET 

RMS$_NORMAL 

RMS$_POS 

RMS$_RAT 


RMS$_ACT 

RMS$_ALQ 

RMS$_ATW 

RMS$_BLN 

RMS$_BUG_DDI 

RMS$_COD 

RMS$_CRE_STM 

RMS$_DEV 

RMS$_DME 

RMS$_DNR 

RMS$_ENQ 

RMS$_ESS 

RMS$_FAB 

RMS$_FLK 

RMS$_FNM 

RMS$_FUL 

RMS$_IAN 

RMS$_IFI 

RMS$_IOP 

RMS$_LAN 

RMS$_MRS 

RMS$_NETFA1L 

RMS$_NPK 

RMS$_PRV 

RMS$_REF 


RMS$_AID 

RMS$_AOP 

RMS$_BKS 

RMS$_BUG 

RMS$_CDA 

RMS$_CRE 

RMS$_CRMP 

RMS$_DFL 

RMS$_DNA 

RMS$_DTP 

RMS$_ENV 

RMS$_EXENQLM 

RMS$_FEX 

RMS$_FNA 

RMS$_FOP 

RMS$_GBC 

RMS$_IBK 

RMS$_IFL 

RMS$_KNM 

RMS$_LNE 

RMS$_NAM 

RMS$_NOD 

RMS$_ORG 

RMS$_QUO 

RMS$_RFM 
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RMS$_RLF 

RMS$_RST 

RMS$_SHR 

RMS$_SUC 

RMS$_SUPPORT 

RMS$_UPI 

RMS$_WPL 


RMS$_RPL 

RMS$_RUNDOWN 

RMS$_SIZ 

RMS$_SUP 

RMS$_SYN 

RMS$_VER 

RMS$_XAB 


RMS$_RSS 

RMS$_SEG 

RMS$_STR 

RMS$_SUPERSEDE 

RMS$_SYS 

RMS$_WLK 


! 
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SDELETE 

The Delete service removes an existing record from a relative or indexed 
file. You cannot use this service when processing sequential files. 

FORMAT 

SYSSDELETE rab [,[err] [,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 


ARGUMENTS 


rab 

VMS usage: 
type: 
access: 
mechanism: 


rab 

longword (unsigned) 

modify 

by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Delete service call. The rab argument is the address of the RAB control 
block. 

err 


VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION A Delete service always applies to the current record. Therefore, immediately 

before invoking the Delete service, you must establish the current record by 
issuing a Find or Get| service. 

Table RMS-9 lists the control block fields read as input by the Delete service. 
For additional informlation on the fields accessed by this service, see Part II. 


RETURN 

VALUES 


Table RMS-9 Delete Service RAB Input Fields 


Field Name 

Option 

Description 

RAB$W_ISI 

RAB$L_ROP 

RAB$V_ASY 

RAB$V_FDL 

Internal stream identifier (required). 

Record-processing options. 

Asynchronous: performs Delete service 
asynchronously. 

Fast delete (applies to indexed files). 


Table RMS-10 lists the control block fields written as output by the Delete 
service. 


Table RMS-10 Delete Service RAB Output Fields 


Field Name 

Description 

RAB$L_STS 

RAB$L_STV 

Completion status code (also returned in register 0). 

Statius value. 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_CDA 

RMS$_DNR 

RMS$_IBF 

RMS$_NET 

RMS$_RAB 

RMS$_RSA 

RMS$_SUPPORT 


RMS$_BLN 

RMS$_CHK 

RMS$_FAC 

RMS$_IOP 

FiMS$_NETFAIL 

RMS$_RNL 

RMS$_STR 

RMS$_SYS 


RMS$_BUG 

RMS$_CUR 

RMS$_FTM 

RMS$_IRC 

RMS$_NORMAL 

RMS$_RPL 

RMS$_SUC 

RMS$_TRE 


RMS$_BUG_DAP 

RMS$_DME 

RMS$_IAL 

RMS$_ISI 

RMS$_PENDING 

RMS$_RRV 

RMS$_SUP 

RMS$_WLK 
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$DISCONNECT 

The Disconnect service breaks the connection between a RAB and a FAB, 
thereby terminating a record stream. All system resources, such as I/O 
buffers and data structure space, are deallocated. 


FORMAT SYS$DISCONNECT rab [,[err][,suc]] 


RETURNS 


VMS usage; 
type: 
access; 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 


ARGUMENTS 


rab 

VMS usage: 
type: 
access: 
mechanism: 


rab 

longword (unsigned) 

modify 

by reference 


RAB control block whose contents are to be used as indirect arguments for the 
Disconnect service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Close service (see $CLOSE) performs an implied disconnect for all 

record streams connected to the FAB. Thus, you need not explicitly issue a 
Disconnect service prior to closing the file. However, if more than one RAB 
is connected to a single FAB, then you must explicitly disconnect the desired 
RAB in order to terminate a particular record stream and leave the others 
active. 

Table RMS-11 lists the control block fields read as input by the Disconnect 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS-11 D 

isconnect Service RAB Input Fields 

Field Name 

De$cription 

RAB$W_ISI 

RAB$L_ROP 

Internal stream identifier (required). 

Record-processing option, RAB$V_ASY. Asynchronous: 
performs Disconnect service asynchronously. 


Table RMS-12 lists the control block fields written as output by the 
Disconnect service. 


Table RMS-12 Disconnect Service RAB Output Fields 


Field Name 

Description 

RAB$W_ISI 

RAB$L_STS 

RAB$L_STV 

Internal stream identifier (zeroed). 

Completion status code (also returned in register 0). 

Status value. 


RETURN 

VALUES 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_BUG_DAP 

RMS$_DNR 

RMS$_NORMAL 

RMS$_STR 

RMS$_SYS 


RMS$_ATR 

RMS$_CDA 

RMS$_ISI 

RMS$_PENDING 

RMS$_SUC 

RMS$_WBE 


RMS$_ATW 

RMS$_CRC 

RMS$_NET 

RMS$_RAB 

RMS$_SUP 

RMS$_WER 


RMS$_BLN 

RMS$_DME 

RMS$_NETFAIL 

RMS$_RSA 

RMS$_SUPPORT 

RMS$_WLK 
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SDISPLAY 

The Display service retrieves file attribute information about a file and 
places this information in fields in the FAB, in XABs chained to the FAB, 
and in a NAM block (if one is requested). 

FORMAT 

SYS$DISPLAY fab [,[err] [,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for 
the Display service call. The fab argument is the address of the FAB control 
block. 

err 

VMS usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION A file must be open for access by a Create or Open service before the Display 

service can be invoked. 

VMS RMS places the file attribute information in the corresponding fields of 
the FAB and specified XABs. If the FAB$L_-NAM field contains a valid NAM 
block address, certain NAM block fields are filled in, including the resultant 
string, and the NAM$B_NOP options are examined. 

Note that the Open and Create services automatically perform an implicit 
Display service (see $OPEN, $CREATE). 

Table RMS-13 lists the control block fields read as input by the Display 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS-13 Display Service FAB and NAM Input Fields 


Field Name 

Option 

Description 

FAB$W_IFI 



Internal file identifier. 

FAB$L_NAM’ 



Name block address. 

FAB$L_XAB’ 



Extended attribute block address. 

NAM$B_NOP 



NAM block options. 


NAM$V_PWD 

Password: indicates that a password 
contained in a DECnet access control 
string, if present in a file specification, 
is to be left unaltered in the expanded 
and resultant strings (instead of being 
replaced by the word "password"). 


NAM$V_NOCONCEAL 

Do not conceal device name: indicates 
that when a concealed device logical 
name is present, the concealed device 
logical name Is to be replaced by 
the actual physical device name (and 
directory. If present) In the resultant 
string. 

^ If you want information about a particular XAB or NAM block, you must pass it to the 
Display service as input. 


Table RMS-14 lists the control block fields written as output by the Display 
service. 

Table RMS-14 Display Service FAB, NAM, and XAB Output Fields 


Field Name 

XAB Type Description 

FAB$L_ALQ 


Allocation quantity in blocks. 

FAB$B_BKS 


Bucket size. 

FAB$W_BLS 


Block size. 

FAB$W_DEQ 


Default file extension quantity. 

FAB$L_DEV 


Device characteristics. 
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Table RMS-14 (Cont.) Display Service FAB, NAM, and XAB Output 

Fields 


Field Name 

XAB Type 

Description 

FAB$B_FAC 


File access. 

FAB$B_FSZ 


Fixed control area size. 

FAB$W_GBC 


Global buffer count. 

FAB$L_MRN 


Maximum record number. 

FAB$W_MRS 


Maximum record size. 

FAB$B_ORG 


File organization. 

FAB$B_RAT 


Record attributes. 

FAB$B_RFM 


Record format. 

FAB$B_RTV 


Retrieval window size. 

FAB$B_SHR 


File sharing. 

FAB$L_STS 


Completion status code (also returned in 
register 0). 

FAB$L_STV 


Status value. 

FAB$L_XAB 


Next XAB address. 


XABALL 

Allocation XAB; see Chapter 8. 


XABDAT 

Date and time XAB; see Chapter 9. 


XABFHC 

File header characteristics XAB; see 

Chapter 10. 


XABITM 

Item list XAB; see Chapter 11. 


XABKEY 

Key definition XAB; see Chapter 13. 


XABPRO 

Protection XAB; see Chapter 14. 


XABRDT 

Revision date and time XAB; see Chapter 15. 


XABSUM 

Summary XAB; see Chapter 17. 

NAM$W_DID 


Directory identification. 

NAM$T_DVI 


Device identification. 

NAM$W_FID 


File identification. 

NAM$L_FNB 


File name status bits. 

NAM$B_RSL 


Resultant string length: Indicates the length 
of the resultant string that is written into 
the buffer whose address is contained in the 
NAM$L_RSA field (if the NAM$L_RSA and 
NAM$B_RSS fields are nonzero). 
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RETURN 

VALUES 


The following conditi 


on values are described in Appendix A: 


RMS$_ACT 

RMS$_BUG_DAP 

RMS$_DNR 

RMS$_FAB 

RMS$_NETFAIL 

RMS$_PRV 

RMS$_SUC 


RMS$_AID 

RMS$_CDA 

RMS$_ESA 

RMS$_IFI 

RMS$_NORMAL 

RMS$_REF 

RMS$_SUP 


RMS$_ATR 

RMS$_COD 

RMS$_ESL 

RMS$_IMX 

RMS$_OK_NOP 

RMS$_RPL 

RMS$_SUPPORT 


RMS$_BLN 

RMS$_DME 

RMS$_ESS 

RMS$_NET 

RMS$_PLG 

RMS$_STR 

RMS$_XAB 
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$ENTER 

The Enter service inserts a file name in a directory. 

FORMAT 

SYSSENTER fab [^err] [,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access; write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Enter service call. The fab argument is the address of the FAB control block. 

err 

VMS usage: ast_procedure 
type; procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 

DESCRIPTION 

The Enter service function is performed automatically by the Create service 
unless you select the FAB$V_TMP option or the FAB$V_TMD option. The 
Enter service, however, allows you to perform this step separately. Note that 
the file must be closed before you invoke the Enter service (FAB$W_IFI must 
be 0). 

When you enter a file name in a directory, no file associated with the FAB 
can be open and no wildcard characters can be used. 
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The Enter service requires many NAM block fields as input. You normally 
precede the Enter service with an Open, Create, or Parse service (see SPARSE) 
and a Search service (see SSEARCH), specifying the same FAB and NAM 
block for each service. 

The optional resultant string is moved to the buffer described by the 
NAM$L_RSA and NAM$B^RSS fields (only if both these fields are nonzero). 
If the file version number of the name string described by the expanded string 
length and address fields of the NAM block is omitted or contains a 0, the 
Enter service scans the entire directory. It assigns a version number that is 
one higher than the highest found (or 1 if none is found). 

The Enter service is not supported for DECnet operations with remote files 
between two VMS systems. 

Table RMS-~15 lists the control block fields read as input by the Enter service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-15 Enter Service FAB and NAM Input Fields 


Field Name 

Description 

FABSWJFI 

Internal file identifier (must be 0). 

FAB$L_NAM 

Name block address. 

NAM$W_DID’ 

Directory identification: identifies the directory in which the 
file name is to be entered. 

NAM$T_DVI' 

Device identification: identifies the device containing the 
directory In which the file name is to be entered. 

NAM$L_ESA 

Expanded string area address: contains file name, type, and 
version to be entered. 

NAM$B_ESL 

Expanded string length. 

NAM$W_FID' 

File Identification: identifies the file to be entered Into the 
directory. 

NAM$L_RSA 

Resultant string area address. 

NAM$B_RSS 

Resultant string size. 

^This field is not supported for DECnet operations. 



Table RMS-16 lists the control block fields written as output by the Enter 
service. 


Table RMS-16 Enter Service FAB and NAM Output Fields 


Field 

Name 

Description 

FAB$L_STS 

Completion status code (also returned in register 0). 

FAB$L_STV 

Status value. 

NAM$B_RSL 

Resultant string length. 
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RETURN 

The following condition values are described in Appendix A: 

VALUES 

RMS$_BLN 

RMS$_CDA 

RMS$_CHN 

RMS$_DEV 


RMS$_DME 

RMS$_DNF 

RMS$_DNR 

RMS$_DVI 


RMS$_ENT 

RMS$_ESA 

RMS$_ESL 

RMS$_FAB 


RMS$_FNF 

RMS$_IFI 

RMS$_NAM 

RMS$_NORMAL 


RMS$_PRV 

RMS$_RSL 

RMS$_RSS 

RMS$_RST 


RMS$_STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 


RMS$_SYS 

RMS$_WLD 

RMS$_WLK 
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SERASE 

The Erase service deletes a VMS RMS disk file and removes the file’s 
directory entry specified in the path to the file. If additional directory 
entries have been created for this file by the Enter service, you must use 
the Remove service to delete them. 

FORMAT 

SYSSERASE fab Uerr] [,suc]] 

RETURNS 

VMS usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Erase service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: 
type: 
access: 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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Using the Erase service to delete a file releases the file's allocated space for 
use by another file. The Erase service does not physically remove the data (as 
does overwriting or zeroing). 

Note that the file must be closed before you invoke the Erase service 
(FAB$W_IFI must be zero). You can, however, delete a file that is currently 
open, if you issue a Close service and specify the FAB$L_FOP field FAB$V-^ 
DLT option. VMS RMS does not allow you to delete files from magnetic tape 
volumes; they must be overwritten. 

If a search list logical name is specified, the file is deleted only if it is found in 
the first resulting search list file specification. 

Table RMS-17 lists the control block fields read as input by the Erase service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-17 Erase Service FAB and NAM Input Fields 


Field Name 

Option 

Description 

FAB$L_DNA 


Default file specification string address. 

FAB$B_DNS 


Default file specification string size. 

FAB$L_FNA 


File specification string address. 

FAB$B_FNS 


File specification string size. 

FAB$L_FOP 


File-processing options. 


FAB$V_NAM’ 

NAM block inputs: allows use of the 
NAM$W_DID, NAM$T_DVI, and NAM$W_ 
FID fields. 

FAB$W_IFI 


Internal file identifier (must be 0). 

FAB$L_NAM 


Name block address. 

NAM$W_DID’ 


Directory identification (input only if the 
FAB$L_FOP field FAB$V_NAM bit is set). 

NAM$T_DVI' 


Device identification (input only if the 
FAB$L_FOP field FAB$V_NAM bit Is set). 

NAM$L_ESA 


Expanded string area address. 

NAM$B_ESS 


Expanded string area size. 

NAM$W_FID’ 


File identification (Input only if the FAB$I_ 

FOP field FAB$V_NAM bit is set). 

NAM$L_RLF 


Related file NAM block address. 


NAM$L_RSA 

Related file resultant string address. 


NAM$B_RSS 

Related file resultant string size. 


NAM$L_FNB 

Related file filename status bits. 


^This field is not supported for DECnet operations. 


Table RMS-18 lists the control block fields written as output by the Erase 
service. Note that the NAM block fields are used for output only if the name 
block address field is specified in the FAB. 
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Table RMS-18 Erase Service FAB and NAM Output Fields 


Field Name 

Description 

FAB$L_STS 

Completion status code (also returned in register 0). 

FAB$L_STV 

Status value. 

NAM$W_DID’ 

Directory identification. 

NAM$T_DVI’ 

Device identification. 

NAM$B_ESL 

Expanded string length. If the NAM$I_ESA field and the 

NAM$B_ESS field are nonzero, and if the FAB$V_NAM bit 
is clear or the NAM$W_DID field contains a zero, VMS RMS 
copies the expanded file specification string to the buffer 
specified by the input NAM$L_ESA field. 

NAM$L_FNB 

File name status bits. 

NAM$B_RSL 

Resultant string length (if NAM$L_RSA and NAM$B_RSS are 
both nonzero on input, the resultant file specification is copied 
to the buffer specified by NAM$I_RSA). 

^This field is not supported for DECnet operations. 


RETURN The following condition values are described in Appendix A: 


VALUES 

RMS$_ACS 

RMS$_BLN 

RMS$_BUG_DAP 

RMS$_BUG_DDI 


RMS$_CDA 

RMS$_CHN 

RMS$_DEV 

RMS$_DIR 


RMS$_DME 

RMS$_DNA 

RMS$_DNF 

RMS$_DNR 


RMS$_DVI 

RMS$_ESA 

RMS$_ESS 

RMS$_FAB 


RMS$_FNF 

RMS$_FNM 

RMS$_IFI 

RMS$_IOP 


RMS$_LNE 

RMS$_MKD 

RMS$_NAM 

RMS$_NET 


RMS$_NETFAIL 

RMS$_NOD 

RMS$_NORMAL 

RMS$_PRV 


RMS$_QUO 

RMS$_RLF 

RMS$_RSS 

RMS$_RST 


RMS$_STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPERSEDE 


RMS$_SUPPORT 

RMS$_SYN 

RMS$_TYP 

RMS$_VER 


RMS$_WLK 
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$EXTEND 


The Extend service increases the amount of space allocated to a VMS 
RMS disk file. This service is most useful for extending relative files and 
indexed files when you are doing block I/O transfers using the Write 
service. 


FORMAT SYSSEXTEND fab [,[err] [,suc]] 


RETURNS 


VMS usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value > 


The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L _STV may contain additional status information. 


ARGUMENTS 


fab 

VMS usage: 
type: 
access: 
mechanism: 


fab 

longword (unsigned) 

modify 

by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Extend service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: 
type: 
access: 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


The Extend service is performed automatically as data is written to a file, 
regardless of the file's organization. However, when you use block I/O, only 
sequential files are automatically extended. Thus, you must use the Extend 
service for relative and indexed files when using block I/O. Also, you may 
want to extend a file explicitly for performance reasons, such as placing a 
large file extent (an extended part of a file) contiguous with the file. 

You must open the file (FAB$W__IFI must not be 0) before you invoke the 
Extend service; otherwise, an error occurs. The file sharing field (FAB$B__ 
FAC) must specify put (FAB$V_PUT) or update (FAB$V_UPD) access to the 
file to be extended. 

The allocation quantity field (FAB$L-_ALQ or XAB$L_ALQ) specifies the 
number of blocks that VMS RMS adds to the file. You can indicate other 
attributes regarding the manner and location for allocation. For example, you 
can indicate that the additional blocks must be allocated contiguously. If you 
do specify contiguous space and not enough contiguous space is available, the 
operation fails. (This extension is not contiguous with the initial file space.) 

If an allocation control XAB is present, its allocation quantity (XAB$L_ALQ) 
and allocation options (XAB$B_AOP, XAB$V^CBT and XAB$V-CTG bits 
only) fields are used instead of the corresponding fields in the FAB. The 
allocation quantity field of the XAB is set to the actual extension size. You 
may specify multiple XABs to extend separate areas of indexed files. 

Table RMS-19 lists the control block fields read as input by the Extend 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS—19 Extend Service FAB Input Fields 


Field Name 

Description 

FAB$L_ALQ 

Allocation quantity; ignored if an allocation XAB is present. 

FAB$L_FOP 

File-processing options: checked to see whether the FAB$V_ 
CTG or FAB$V_CBT bit is set to indicate contiguous allocation 
(ignored for allocation XAB). 

FAB$W_IFI 

Internal file identifier (must not be 0). 

FAB$L_XAB 

Extended attribute block address. Only an allocation XAB 
(XABALL) is processed. 


Table RMS-20 lists the control block fields written as output by the Extend 
service. 


Table RMS—20 Extend Service FAB Output Fields 


Field Name 

Description 

FAB$L_ALQ 

Allocation quantity: contains the actual extension allocation 
value if no allocation XAB Is present. 

FAB$L_STS 

Completion status code (also returned In register 0). 

FAB$L_STV 

Status value (contains the total number of blocks allocated, 
totaled across all allocation XABs). 
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RETURN 

The following condition values are described in Appendix A: 

VALUES 

RMS$_ACT 

RMS$_AID 

RMS$_ALN 

RMS$_ALQ 


RMS$_AOP 

RMS$_ATR 

RMS$_ATW 

RMS$_BLN 


RMS$_BUG_DAP 

RMS$_CDA 

RMS$_COD 

RMS$_DME 


RMS$_EXT 

RMS$_FAB 

RMS$_FAC 

RMS$_FUL 


RMS$_IFI 

RMS$_IMX 

RMS$_IOP 

RMS$_LEX 


RMS$_NET 

RMS$_NETFAIL 

RMS$_NORMAL 

RMS$_PLG 


RMS$_RPL 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 


RMS$_SUPPORT 

RMS$_SYS 

RMS$_WBE 

RMS$_WER 


RMS$_WLK 

RMS$_WPL 

RMS$_XAB 
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$FIND 

The Find service locates a specified record in a file and returns its record 
file address in the RAB$W_RFA field of the RAB. The Find service can be 
used with all file organizations. 

FORMAT 

SYS$FIND rab [,[err] [,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Find service call. The rab argument is the address of the RAB control 
block. 

err 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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The Find service gives you the following functional capabilities: 

• You can skip records when you are accessing a file sequentially by 
making successive invocations of the Find service. 

• You can establish the current record context prior to invoking an Update, 
Delete, or Truncate service. 

• You can establish a random access starting point in a file for subsequent 
sequential access operations such as the Get service. 

When you follow the Find service with a sequential access operation, such as 
the Get service, the current record context is established by the Find service 
and the sequential access operation establishes a new sequential access context. 
Conversely, when you follow the Find service with a nonsequential access 
operation such as a Delete service or an Update service, the sequential access 
context remains the same as it was prior to the Find service. 

Table RMS--21 lists the control block fields read as input by the Find service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-21 

Find Service RAB Input Fields 

Field Name 

XAB Type 

Description 

RAB$W_ISI 


Internal stream identifier (required). 

RAB$L_KBF 


Key buffer address (used only if RAB$B_ 
RAC field contains RAB$C_KEY or if 
RAB$B_RAC contains RAB$C_SEQ and the 

RAB$I_ROP field RAB$V_LIM option is 

set). 

RAB$B_KRF 


Key of reference (used only with indexed 
files and if RAB$B_RAC contains RAB$C_ 
KEY). 

RAB$B_KSZ 


Key size (used only if RAB$B_RAC field 
contains RAB$C_KEY or if RAB$B_RAC 
contains RAB$C_SEQ and the RAB$L_ROP 
field RAB$V_LIM option is set). 

RAB$L_PBF’ 


Prompt buffer address (applies to terminal 
devices only). 

RAB$B_PSZ’ 


Prompt buffer size (applies to terminal 
devices only). 

RAB$B_RAC 


Record access mode (RAB$C_SEQ, 
RAB$C_KEY, RAB$C_RFA)2. 

RAB$W_RFA 


Record file address (used only if RAB$B_ 
RAC contains RAB$C_RFA). 

RAB$L_ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Find services 
asynchronously. 

^This field is not supported for DECnet operations. 

^The default for the RAB$B_RAC field 

is RAB$C_SEQ. 
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Table RMS-21 (Cont.) Find Service RAB Input Fields 


Field Name XAB Type 

Description 

RAB$V_CVT’ 

Convert: changes characters to uppercase 
for a Find service to a terminal device. 

RAB$V_KGE^ 

Key is greater than or equal to compared 
value (applies only to indexed files). 

RABSV-KGT'^ 

Key is greater than compared value (applies 
only to indexed files). If neither RAB$V_ 
KGE nor RAB$V_KGT is specified, a key 
equal match Is made. 

RAB$V_LIM 

Limit: the key value described by the KBF 
and KSZ fields is to be compared to the 
value in the record accessed sequentially. 

RAB$V_NLK 

No lock: specifies that the record accessed 
through the Find service is not to be locked. 

RAB$V_NXR 

Nonexistent record processing: specifies 
that if the record directly accessed through 
a Find service does not exist, the service Is 
to be performed anyway. 

RAB$V_PMT’ 

Prompt indicates that the contents of the 
prompt buffer are to be used as a prompt 
for a Find service to a terminal device. 

RAB$V_PTA’ 

Purge type-ahead buffer: eliminates any 
information that may be in the type-ahead 
buffer for a Find service to a terminal 
device. 

RAB$V_RAH’ 

Read ahead: used with multiple buffers to 
indicate read-ahead operations (sequential 
files only). 

RAB$V_REA 

Lock for read: allows other users read 
access to the record. 

RAB$V_RLK 

Read of locked record allowed: specifies 
that a user who locks a record Is allowing 
the locked record to be read by other 
accessors. 

RAB$V_RNE' 

Read no echo: indicates that input data 
entered on the keyboard is not echoed 
(displayed) on the terminal device. 

RAB$V_RNF’ 

Read no filter: Indicates that CTRL/U, 
CTRL/R, and DELETE are not to be 
considered control commands on terminal 
input, but are to be passed to the 
application program. 

RAB$V_RRL 

Read regardless of lock: read the record 
even if another stream has locked the 
record. 


^This field is not supported for DECnet operations. 

^This symbolic offset is logically synonymous with RAB$V_EQNXT. 
"^This symbolic offset is logically synonymous with RAB$V_NXT. 
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Table RMS-21 (Cont.) Find Service RAB Input Fields 


Field Name XAB Type Description 



RAB$V_TMO’ 

Timeout: indicates that the contents of 
the timeout period field (RAB$B_TMO) is 
to be used on a Find request for a locked 
record (when the RAB$V_WAT option Is 
also specified) or for a terminal or mailbox 
device. 


RAB$V_ULK 

Manual unlocking: specifies that a record 
cannot be automatically unlocked. 


RAB$V_WAT 

Wait: if record is locked, wait until It Is 
available. 

RAB$B_TMO’ 


Timeout period: indicates the maximum 
number of seconds that VMS RMS can use 
to complete a Find request. 


'This field is not supported for DECnet operations. 


Table RMS-22 lists the control block fields written as output by the Find 
service. 

Table RMS-22 Find Service RAB Output Fields 


Field Name Description 


RAB$L_BKT 

Bucket code: set to the relative record number for relative files 
accessed sequentially. 

RAB$W_RFA 

Record file address. 

RAB$L_STS 

Completion status code (also returned in register 0). 

RAB$L_STV 

Status value. 


The record address (RAB$L_RBF) field and the record size (RAB$W_RSZ) 
field are undefined after a Find service. 


RETURN 

The following condition values are described in Appendix A: 

VALUES 

RMS$_ACT 

RMS$_ANI 

RMS$_ATR 


RMS$_ATW 

RMS$_BES 

RMS$_BLN 


RMS$_BUG 

RMS$_BUG_DAP 

RMS$_CDA 


RMS$_CHK 

RMS$_CONTROLC 

RMS$_CONTROLY 


RMS$_DEADLOCK 

RMS$_DEL 

RMS$_DME 


RMS$_DNR 

RMS$_EOF 

RMS$_EXENQLM 


RMS$_FAC 

RMS$_FTM 

RMS$_IBF 


RMS$_IOP 

RMS$_IRC 

RMS$_ISI 


RMS$_KBF 

RMS$_KEY 

RMS$_KRF 


RMS$_KSZ 

RMS$_MRN 

RMS$_NET 
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RMS$_NETFAIL 

RMS$_OK_DEL 

RMS$_OK_RNF 

RMS$_PBF 

RMS$_PLG 

RMS$_REF 

RMS$_RHB 

RMS$_ROP 

RMS$_RSA 

RMS$_SUC 

RMS$_SYS 

RMS$_WBE 


RMS$_NORMAL 

RMS$_OK_LIM 

RMS$_OK_RRL 

RMS$_PENDING 

RMS$_RAB 

RMS$_RER 

RMS$_RLK 

RMS$_RPL 

RMS$_SQO 

RMS$_SUP 

RMS$_TMO 

RMS$_WER 


RMS$_OK_ALK 

RMS$_OK_RLK 

RMS$_OK_WAT 

RMS$_PES 

RMS$_RAC 

RMS$_RFA 

RMS$_RNF 

RMS$_RRV 

RMS$_STR 

RMS$_SUPPORT 

RMS$_TRE 

RMS$_WLK 
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$FLUSH 

The Flush service writes out all modified I/O buffers and file attributes 
associated with the file. This ensures that all record activity up to the 
point at which the Flush service executes is actually reflected in the file. 

FORMAT 

SYSSFLUSH rab [,[err] [,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 


ARGUMENTS 


rab 

VMS usage: 
type: 
access: 
mechanism: 


rab 

longword (unsigned) 

modify 

by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Flush service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Flush service is not required at any time, not even with a Close service, 

because the Close service performs the Flush functions implicitly. 

During asynchronous operations, you must wait for any I/O activity to 
complete before issuing a Flush service. You can also issue a Flush service 
after receiving notification of completion through an asynchronous system 
trap (AST). 

Table RMS-23 lists the control block fields read as input by the Flush service 
For additional information on the fields accessed by this service, see Part II. 


Table RMS—23 Flush Service RAB Input Fields 


Field Name 

Description 

RAB$W_ISI 

RAB$L_ROP 

Internal stream identifier (required). 

Record-processing option: RAB$V_ASY only. Asynchronous: 
performs Flush services asynchronously. 

Table RMS-24 lists the control block fields written as output by the Flush 
service. 

Table RMS- 

-24 Flush Service RAB Output Fields 

Field Name 

Description 

RAB$L_STS 

RAB$L_STV 

Completion status code (also returned in register 0). 

Additional status information. 


RETURN 

The following condition values are described in Appendix A: 

VALUES 

RMS$_ACT 

RMS$_ATR 

RMS$_ATW 

RMS$_BLN 


RMS$_BUG_DAP 

RMS$_CDA 

RMS$_DME 

RMS$_DNR 


RMS$_ISI 

RMS$_NET 

RMS$_NETFAIL 

RMS$_NORMAL 


RMS$_PENDING 

RMS$_RAB 

RMS$_RSA 

RMS$_STR 


RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 

RMS$_SYS 


RMS$_WBE 

RMS$_WER 

RMS$_WLK 
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$FREE 

The Free service unlocks all records that were previously locked for the 
record stream. 

FORMAT 

SYS$FREE rab [,[err] [,suc]] 

RETURNS 

VMS usage: cond_value 
type; longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS usage: rab 

type; longword (unsigned) 

access; modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Free service call. The rab argument is the address of the RAB control 
block. 

err 

VMS usage; ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism; by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Free service unlocks all records previously locked for the record stream 

(see also $RELEASE). If no records are locked for the record stream, VMS 
RMS returns a status code of RMS$_RNL. 

Table RMS-25 lists the control block fields read as input and written as 
output by the Free service. For additional information on the fields accessed 
by this service, see Part II. 


Table RMS—25 Free Service RAB Input and Output Fields 


Use 

Field 

Name 

Description 

Input 

RAB$W_ISI 

Internal stream identifier (required). 

Output 

RAB$L_STS 

Completion status code (also returned in register 0). 


RAB$L_STV 

Status value. 


RETURN 

The following condition values are described in Appendix A: 

VALUES 

RMS$_ACT 

RMS$_BLN 

RMS$_BUG_DAP 

RMS$_ISI 


RMS$_NET 

RMS$_NETFAIL 

RMS$_NORMAL 

RMS$_PENDING 


RMS$_RAB 

RMS$_RNL 

RMS$_RSA 

RMS$_STR 


RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 
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$GET 

The Get service retrieves a record from a file. 

Note; When you invoke the GET service, RMS takes control of the record buffer 
and may modify it. RMS returns the record size and only guarantees the 
contents from where it accessed the record to the completion of the record. 


FORMAT SYSSGET rab [,[err][,suc]] 


RETURNS 


ARGUMENTS 


VMS usage; 
type: 
access; 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 


rab 

VMS usage; 
type: 
access; 
mechanism: 


rab 

longword (unsigned) 

modify 

by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Get service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: 
type: 
access; 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


The Get service is performed by using one of three possible record access 
modes, as specified by the record access (RAB$B_RAC) field. The three 
record access modes are sequential (SEQ), which is the default, random by 
key (KEY), and random by record file address (RFA). 

Relevant Record Access Modes 

The sequential access mode is relevant for all file organizations as well as for 
all devices. It is the only access mode allowed for nondisk devices, such as 
terminals, mailboxes, and magnetic tape devices. In this mode, records are 
retrieved from a given file in the same order in which they were written to 
that file. This is not the case, however, for records retrieved from indexed 
files. Sequential Get services for indexed files return records by key value in 
the specified sort order, ascending or descending. The next record's key of 
reference for sequential access to indexed files is established by one of the 
following services: 

• Connect 

• Rewind (see $REWIND) 

• Find or Get using random access by key 

• Find or Get using random access by RFA 

When you use random access by key with any operations related to these 
services, the key of reference is established by the key of reference field 
(RAB$B_KRF). When you use random access by RFA in conjunction with a 
Find or Get service, however, the key of reference is always set to the primary 
key. 

You can use random access by key to retrieve records by key value. For 
relative files and sequential files having fixed-length records, the key value 
is the relative record number. For indexed files, the key value depends on 
the data type of the specified key of reference. The key value is used to 
search the index of the specified key of reference to locate the desired record. 
A random access by key also establishes the next record for subsequent 
sequential retrieval. This type of access may be used in this way to establish 
a starting point for sequential retrieval of records at other than the beeinnine 
of the file. ® ^ 

You can use random access by RFA to retrieve records directly from files 
residing on disk devices. Fiowever, a record's address can be determined only 
if the record has been accessed previously. The Find, Get, and Put services 
each return the RFA value as output in the RAB$W_RFA field. 

Random access of records in a file is prohibited when you open the file and 
select the FAB$V_SQO option; that is, if you specify sequential operations 
only. 

Input from Stream Format Files 

For stream format files, VMS RMS fills the user buffer with data until a 
terminator is reached. If the buffer fills before a terminator is encountered, 
the remainder of the data preceding the terminator is discarded, and an 
RMS$_RTB error is returned. If the terminator for stream format (FAB$B_ 
RFM contains FAB$C_STM) is not CRLF (carriage return followed by line 
feed), the terminator is stored in the buffer following the record and included 
in the size of the record. 
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Input from Terminal Devices 

There are two methods of obtaining input from a terminal using VMS RMS: 

1 Using the RAB$L_ROP field to define the terminal input operation. 
Certain options applicable to the RAB$L_ROP field are used for terminal 
device input, such as whether a prompt is to be displayed and whether 

a time limit between characters is enforced. These options may require 
certain information to be placed in other fields of the RAB (see Chapter 7). 
The maximum buffer size is 512 bytes. 

2 Using an item list to define the terminal input operation in conjunction 
with a terminal XAB (XABTRM). The ETO option of the RAB$L_ROP 
field must be set and the user must provide an item list in the calling 
program, which VMS RMS passes to the terminal driver using the item 
list address and length specified in the XABTRM (see Chapter 18). This 
method allows use of any terminal input option supported by the terminal 
driver, in contrast to the subset of RAB$L_ROP options available using 
the other method. The maximum buffer size is 512 bytes. 

VMS RMS uses the standard terminator set when performing input operations 
from terminal devices. The second longword of the I/O status block used 
is returned in the RAB$L_STV field. The terminating character is returned 
in the lower word of the status value field (RAB$W_STV0); however, note 
that with extended terminal operations, the terminating character is in the 
first byte of RAB$W_STV0, not in the entire RAB$W_STV0 word. More 
information about the second longword of the I/O status block is available in 
the VMS I/O User’s Reference Manual: Part I in the VMS I/O User's Reference 
Volume. The RAB$W_STV0 field is device dependent for terminal devices. 

The CTRL/Z character terminates the Get service and acts as an end-of-file 
marker for VMS RMS. If you enter a CTRL/Z in response to a request for 
data, VMS RMS returns the completion status code for end-of-file (RMS$_ 
EOF). VMS RMS takes the data you enter before the CTRL/Z but the next 
Get service returns a single end-of-file error (RMS$_EOF) without accepting 
any further input from the device. VMS RMS resumes taking input if you 
request a subsequent Get service. 

VMS RMS also supports the use of escape sequences from terminal devices 
that are accessed locally and have escape sequences enabled. Escape 
sequences for a terminal are enabled by the SET TERMINAL command 
(described in the VMS DCL Dictionary). Escape sequences are returned in the 
record buffer. The record size (RAB$W_RSZ) is the offset within the buffer 
(RAB$L_RBF) to the beginning of the escape sequence. The high-order word 
of the status value field (RAB$W_STV2) contains the length of the escape 
sequence, except for extended terminal operations. In this case, the escape 
sequence length is returned in the first byte of RAB$W_STV2, not the entire 
RAB$W_STV2 word, and the terminator position is returned in the second 
byte of the RAB$W_STV2 word. When a partial escape sequence warning 
(RMS$_PES) is returned, the remaining characters in the escape sequence are 
returned by the next read request from the terminal. 
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Input from Mailbox Devices 

Mailboxes may be used to synchronize activity across cooperating processes. 
Normally, a Get service from a mailbox device is not completed until a record 
is present in the mailbox. When the Get service is completed, the status value 
field (RAB$L_STV) contains the process identification (PID) of the process 
that put the record into the mailbox. However, if the timeout (TMO) record 
option is specified with a value of 0 in the timeout field and if no messages 
are present in the mailbox, then the Get service returns an end-of-file error 
(RMS$_EOF). This technique assures your process of an immediate return, 
whether or not messages are present in the mailbox. 

Using the RAB$L_STV Field 

The RAB$L_STV field contains additional status information for a number of 
situations. When the completion status is a record-too-big warning (RMS$_ 
RTB), RAB$L_STV contains the total record size. For record-oriented devices 
such as terminals and mailboxes, the second longword of the I/O status 
block is returned in the RAB$L_STV field, whenever the completion status 
(RAB$L_STS) is a success code. The alternate field definitions of RAB$W_ 

ST VO and RAB$W_STV2 are provided to reference the respective low- and 
high-order words of the RAB$L_STV field. The record size field (RAB$W_ 
RSZ) always reports the amount of data returned, regardless of the completion 
status (RAB$L_STS). The presence of valid data on error conditions may then 
be detected by checking the record size field. 

The User Record Area 

The Get service always requires the presence of a user record area, as 
specified by the user record buffer address (RAB$L_UBF) and user buffer 
area size (RAB$W_USZ) fields in the RAB. 

For undefined format files, the RAB$W_USZ field defines the amount of data 
to be returned on each Get service. 

Table RMS-26 lists the control block fields read as input by the Get service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS—26 Get Service RAB Input Fields 
Option or 

Field Name XAB Type Description 


RAB$W_ISI 

RAB$L_KBF 


RAB$B_KRF 

RAB$B_KSZ 


Internal stream identifier (required). 

Key buffer address: used only if the 
RAB$B_RAC field contains RAB$C_KEY, 
or if the RAB$B_RAC field contains 
RAB$C_SEQ and you select the RAB$V_ 
LIM option. 

Key of reference: used only with indexed 
files and only if the RAB$B_RAC field 
contains RAB$C_KEY. 

Key buffer size: used only if the RAB$B_ 
RAC field contains RAB$C_KEY, or if the 
RAB$B_RAC field contains RAB$C_SEQ 
and you select the RAB$V_LIM option. 
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Table RMS-26 (Cont.) Get Service RAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

RAB$L_PBF’ 


Prompt buffer address (applies to 
terminal devices only). 

RAB$B_PSZ’ 


Prompt buffer size (applies to terminal 
devices only). 

RAB$B_RAC 


Record access mode (RAB$C_SEQ, 
RAB$C_KEY, RAB$C_RFA).2 

RAB$W_RFA 


Record file address: used only If the 
RAB$B_RAC field contains RAB$C_RFA. 

RAB$L_RHB 


Record header buffer: used for the 
fixed-length control area of VFC records. 

RAB$L_ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Get services 
asynchronously. 


RAB$V_CVT' 

Convert: changes characters to 
uppercase for a Get service to a terminal 
device. 


RAB$V_ETO’ 

Extended terminal operation: specifies 
that an XABTRM and an item list 
are used to define the terminal input 
operation. If this option is specified, no 

other RAB$I_ROP options applicable to 

terminal devices can be used. 


RAB$V_KGE^ 

Search for equal key value or next key 
value according to sort order (applies 
only to indexed files). 


RAB$V_KGT^ 

Search for next key value according to 
sort order; if neither the RAB$V_KGE 
(RAB$V_EQNXT) option nor the RAB$V_ 
KGT (RAB$V_NXT) option is specified, 
VMS RMS looks for a key match. 


RAB$V_LIM 

Limit: specifies that the key value 

described by the RAB$I_KBF field and 

the RAB$B_KSZ field Is to be compared 
with the value In the record accessed 
sequentially. 


RAB$V_LOC' 

Locate mode: specifies that Get service 
record operations use locate mode. 


RAB$V_NLK 

No lock: specifies that the record 
accessed through the Get service Is 
not to be locked. 


’This field is not supported for DECnet operations. 
2The default for the RAB$B_RAC field is RAB$C_SEQ. 


^This symbolic offset is logically synonymous with RAB$V_EQNXT. 
^This symbolic offset is logically synonymous with RAB$V_NXT. 
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Table RMS—26 (Cont.) Get Service RAB Input Fields 


Option or 

Field Name XAB Type Description 


RAB$V_NXR 

Nonexistent record processing: specifies 
that if the record directly accessed 
through a Get service does not exist, the 
service is to be performed anyway. 

RAB$V_PMT’ 

Prompt: indicates that the contents of 
the prompt buffer are to be used as a 
prompt on a Get service to a terminal 
device. 

RAB$V_PTA’ 

Purge type-ahead: eliminates any 
information that may be in the type- 
ahead buffer, on a Get service to a 
terminal device. 

RAB$V_RAH’ 

Read ahead: used with multiple buffers 
to indicate read-ahead operations 
(sequential files only). 

RAB$V_REA 

Lock for read: allows other users read 
access to the record. 

RAB$V_RLK 

Read of locked record allowed: specifies 
that a user who locks a record for 
modification Is allowing the locked record 
to be read by other accessors. 

RAB$V_RNE’ 

Read no echo Indicates that input data 
entered on the keyboard is not echoed 
(displayed) on the terminal device. 

RAB$V_RNF’ 

Read no filter: Indicates that CTRL/U, 
CTRL/R, and DELETE are not to be 
considered control commands on 
terminal input, but are to be passed 
to the application program. 

RAB$V_RRL 

Read regardless of lock: read the record 
even if another stream has locked the 
record. 

RAB$V_TMO’ 

Timeout: indicates that the content of 
the timeout period field (RAB$B_TMO) is 
to be used. 

RAB$V_ULK 

Manual unlocking: specifies that records 
cannot be automatically unlocked. 

RAB$V_WAT 

Walt: if record is locked, wait until it is 
available. 


^This field is not supported for DECnet operations. 
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Table RMS-26 (Cent.) Get Service RAB Input Fields 


Option or 

Field Name XAB Type Description 


RAB$B_TMO^ 

Timeout period: indicates the maximum 
number of seconds that VMS RMS 
allows between characters for a Get 
service to terminal and mailbox devices 
only, or the maximum number of seconds 
VMS RMS waits for a locked record 
if you specify the RAB$V_TMO and 
RAB$V_WAT options in the RAB$I— 

ROP field. 

RAB$L_UBF 

User record buffer address (required). 

RAB$W_USZ 

User record buffer size (required). 

RAB$L_XAB 

XABTRM^ Next XAB address: indicates the address 

of an XABTRM control block (the 
RAB$L_ROP field RAB$V_ETO option 
must be set for an extended terminal 
operation). 

^This field is not supported for DECnet operations. 


Table RMS-27 lists the control block fields written as output by the Get 

service. 



Table RMS- 

■27 Get Service RAB Output Fields 

Field Name 

Description 


RAB$L_BKT 

Bucket code: set to the relative 
when the record access mode is 

record number for relative files 
sequential. 

RAB$L_RBF 

Record buffer address. 


RAB$W_RFA 

Record file address. 


RAB$W_RSZ 

Record size. 


RAB$L_STS 

Completion status code (also returned in register 0). 

RAB$L_STV 

Status value (contains a terminator character for terminal input 
or the record length if the requested record is too large for the 
user buffer area). 


RETURN 

The following condition values are described in 

Appendix A: 

VALUES 

RMS$_ACT 

RMS$_ANI 

RMS$_BES 


RMS$_BLN 

RMS$_BUG 

RMS$_BUG_DAP 


RMS$_CDA 

RMS$_CHK 

RMS$_CONTROLC 


RMS$_CONTROLY 

RMS$_DEADLOCK 

RMS$_DEL 


RMS$_DME 

RMS$_DNR 

RMS$_EOF 


RMS$_ENQ 

RMS$_EXENQLM 

RMS$_EXP 
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RMS$_FAC 

RMS$_IOP 

RMS$_KBF 

RMS$_KSZ 

RMS$_NETFAIL 

RMS$_OK_DEL 

RMS$_OK_RNF 

RMS$_PBF 

RMS$_PLG 

RMS$_RER 

RMS$_RLK 

RMS$_RPL 

RMS$_RTB 

RMS$_SUC 

RMS$_SYS 

RMSS-TRE 

RMS$_WER 


RMS$_FTM 

RMS$_IRC 

RMS$_KEY 

RMS$_MRN 

RMS$_NORMAL 

RMS$_OK_LIM 

RMS$_OK_RRL 

RMS$_PENDING 

RMS$_RAB 

RMS$_RFA 

RMS$_RNF 

RMS$_RRV 

RMS$_SQO 

RMS$_SUP 

RMS$_TMO 

RMS$_UBF 

RMS$_WLK 


RMS$_IBF 

RMS$_ISI 

RMS$_KRF 

RMS$_NET 

RMS$_OK_ALK 

RMS$_OK_RLK 

RMS$_OK_WAT 

RMS$_PES 

RMS$_RAC 

RMS$_RHB 

RMS$_ROP 

RMS$_RSA 

RMS$_STR 

RMS$_SUPPORT 

RMS$_TNS 

RMS$_WBE 

RMS$_XAB 
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SNXTVOL 

The Next Volume service allows you to process the next tape volume in 
a multiple volume set. This service applies only to files on magnetic tape 
volumes. 

FORMAT 

SYS$NXTVOL rab [,[err][,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Next Volume service call. The rab argument is the address of the RAB 
control block. 

err 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


You use the Next Volume service when you want to proceed to the next 
volume in the set before the end of the current volume (EOV label) is reached 
on input, or before the end-of-tape (EOT) mark is reached on output. VMS 
RMS positions your process to the first file section on the next volume. File 
sections occur when a file is written on more than one volume, the portion of 
the file on each of the volumes constituting a file section. 

When you perform a Next Volume service for input files, VMS RMS responds 
as follows. 

• If the current volume is the last volume of the set, VMS RMS reports 
end-of-file information. 

• If another file section exists, the next volume is mounted. When 
necessary, the current volume is rewound and a request to mount the 
next volume is issued to the operator. 

• The header label (HDRl) of the file section on the newly mounted volume 
is read. If this is not the volume being sought, the operator is requested 
to mount the correct volume. 

When you perform a Next Volume service for output files, the following 
sequence occurs: 

1 The file section on the current volume is closed with the appropriate 
end-of-volume labels, and the volume is rewound. 

2 The next volume is mounted. 

3 A file with the same file name and the next higher file section number is 
opened for output, and processing continues. 

If your program is operating asynchronously, it must wait for any I/O activity 
on this volume to complete before issuing a Next Volume service. 

The Next Volume service performs a Flush service for write-accessed volumes 
(see $FLUSH), thus writing the I/O buffers on the current volume before 
creating the next file section. If this is an input-only file, then all records 
currently contained in the I/O buffers are lost, and the next Get service 
returns the first record on the next volume. 

The Next Volume service is not supported for DECnet operations for remote 
file access between two VMS systems. 

Table RMS—28 lists the control block fields read as input and written as 
output by the Next Volume service. For additional information on the fields 
accessed by this service, see Part 11. 
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Table RMS-28 Next Volume Service RAB Input and Output Fields 


Use 

Field Name 

Description 

Input 

RAB$W_ISI 

Internal stream identifier (required). 


RAB$L_ROP 

Record-processing option, RAB$V_ASY. 
Asynchronous only: performs Next Volume service 
asynchronously. 

Output 

RAB$L_STS 

Completion status code (also returned in 
register 0). 


RAB$L_STV 

Status value. 



RETURN 

The following condition values are described in Appendix A: 

VALUES 

RMS$_ACT 

RMS$_BLN 

RMS$_CDA RMS$_DME 


RMS$_DNR 

RMS$_DPE 

RMS$_I0P RMS$_ISI 


RMS$_NORMAL 

RMS$_PENDING 

RMS$_RAB RMS$_RSA 


RMS$_STR 

RMS$_SUC 

RMS$_SUP RMS$_SUPPORT 


RMS$_SYS 
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$OPEN 

The Open service makes an existing file available for processing by your 
program. The Open service specifies the type of record access to be used 
and determines whether or not the file can be shared. The Open service 
also performs an implicit Display service. 

FORMAT 

SYS$OPEN fab [,[err] [,suc]] 

RETURNS 

VMS usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Open service call. The fab argument is the address of the FAB control block. 

err 

VMS usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


You must open a file to perform any record operations and most file 
operations. If any XABs are chained to the FAB, VMS RMS places the 
attribute values in the fields of the appropriate XAB. If you specify a NAM 
block in the FAB, the contents of the device, directory, and file identification 
fields can be used with the open-by-NAM-block option to open the file. The 
NAM block fields are filled in with auxiliary file specification information. 

Table RMS-29 lists the control block fields read as input by the Open service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-29 Open Service FAB and XAB Input Fields 


Field Name 

Option or 

XAB type 

Description 

FAB$V_CHAN_M0DE3 


Channel access mode assignment. 

FAB$W_DEQ 


Default file extension quantity: if 
a nonzero value is present in this 
field, it applies only to this open of 
the file. 

FAB$L_DNA 


Default file specification string 
address. 

FAB$B_DNS 


Default file specification string size. 

FAB$B_FAC 


File access field. 


FAB$V_BIO 

Block I/O access. 


FAB$V_BRO 

Block or record I/O. 


FAB$V_DEL 

Delete access. 


FAB$V_GET’ 

Read access. 


FAB$V_PUT 

Write access. 


FAB$V_TRN 

Truncate access. 


FAB$V_UPD 

Update access. 

FAB$L_FNA2 


File specification string address. 

FAB$B_FNS2 


File specification string size. 

FAB$L_FOP 


File-processing options. 


FAB$V_DFW^ 

Deferred write: indicates that 
writing back to the file from the 
modified buffer is deferred (applies 
to relative and indexed files only). 


FAB$V_DLT 

Delete: indicates the file Is to be 
deleted when it Is closed. 


FAB$V_NAM^ 

Name block inputs: indicates that 


the NAM$W_FID, NAM$W_DID, 
and NAM$T_DVI fields in the 
specified NAM block are to be 
used to describe the file. 


^This is the default value supplied by VMS RMS. 
^These fields must be specified by the user. 

^This field is not supported for DECnet operations. 
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Table RMS-29 (Cent.) Open Service FAB and XAB Input Fields 


Field Name 

Option or 

XAB type 

Description 


FAB$V_NFS2 

Non-file-structured: indicates that 
the accessed volume Is to be 
processed in a non-flle-structured 
manner. 


FAB$V_OFP 

Output file parse: specifies that 
the related file resultant file 
specification string, if used, is 
to provide file name and file type 
defaults only. 


FAB$V_RCK 

Read-check: Indicates that transfers 
from disk are to be checked by a 
followup, read-compare operation. 


FAB$V_RWC 

Rewind on close (applies to 
magnetic tapes only). 


FAB$V_RWO 

Rewind on open (applies to 
magnetic tapes only). 


FAB$V_SCF^ 

Submit command file: indicates 
that the file is to be submitted as a 
batch-command file to the process 
default batch queue (SYS$BATCH) 
when the file is closed (applies to 
sequential files only). 


FAB$V_SPL^ 

Spool: indicates that the file is to 
be spooled to the process default 
print queue (SYS$PRINT) when the 
file is closed (applies to sequential 
files only). 


FAB$V_SQO 

Sequential only: indicates that 
the file can be processed In a 
sequential manner only. 


FAB$V_TEF 

Truncate at end of file: Indicates 
that unused space allocated to a 
file is to be deallocated when that 
file is closed (applies to sequential 
files only). 


FAB$V_UFO^ 

User file open: Indicates the file 
is to be opened only (no further 
VMS RMS processing of that file is 
allowed). 

FAB$B_FSZ 

FAB$W_IFI 

FAB$V_WCK 

Write-check: indicates that 
transfers to disk are to be followed 
by a read-compare operation. 

Fixed control area size: unit record 
devices only. 

Internal file identifier (must be 0). 


^This field is not supported for DECnet operations. 
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Table RMS-29 (Cont.) Open Service FAB and XAB Input Fields 


Field Name 

Option or 

XAB type 

Description 

FAB$V_LNM_MODE^ 


Specifies the logical name 
translation access mode. 

FAB$L_NAM 


Name block address. 

FAB$B_RAT 


Record attributes; only for process 
permanent files with print file 
format. 

FAB$B_RFM 


Record format; unit record devices 
only. 

FAB$B_RTV^ 


Retrieval window size. 

FAB$B_SHR 


File-sharing field. 


FAB$V_SHRDEL 

Shared delete access. 


FAB$V_SHRGET 

Shared read access. 


FAB$V_MSE^ 

Multistream access; also used with 
the FAB$V_MSE and FAB$V.^GET 
bits to specify a read-only global 
buffer cache when global buffering 
is enabled. 


FAB$V_NIL 

No shared access. 


FAB$V_SHRPUT 

Shared write access. 


FAB$V_SHRUPD 

Shared update access. 


FAB$V_UPI 

Shared write access for block I/O 
(applies to sequential files only). 

FAB$L_XAB'' 


Extended attribute block address. 


XABITM 

Item list XAB; see Chapter 11. 


^This field is not supported for DECnet operations. 

^The appropriate XAB must be specified as input if you desire information about that 
particular XAB on output from the Open Service. 


Table RMS-30 lists the control block fields written as output by the Open 
service. 


Table RMS-30 Open Service FAB and XAB Output Fields 

Option or 

Field Name XAB Type Description 

FAB$I_ALQ Allocation quantity: contains the highest 

numbered block allocated to the file. 


FAB$B_BKS 

FAB$W_BLS 

FAB$W_DEQ 


Bucket size (does not apply to sequential 
files). 

Device block size (applies only to sequential 
files). 

Default file extension quantity. 
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Table RMS-30 (Cent.) Open Service FAB and XAB Output Fields 


Field Name 

Option or 

XAB Type 

Description 

FAB$L_DEV 


Device characteristics. 

FAB$B_FAC 


File access. 

FAB$L_FOP 


File-processing options. 


FAB$V_CBT 

Contiguous best try: indicates that the file 
is allocated contiguously on a "best effort" 
basis. 


FAB$V_CTG 

Contiguous: indicates that space for the file 
is allocated contiguously. 


FAB$V_RCK 

Read-check: transfers are followed up by a 
read-compare operation. 


FAB$V_WCK 

Write-check: transfers are followed up by a 
read-compare operation. 

FAB$B_FSZ 


Fixed-length control area size (applies only to 
VFC records). 

FAB$W_GBC 


Global buffer count. 

FAB$W_IFI 


Internal file Identifier. 

FAB$L_MRN 


Maximum record number (for relative files 
only). 

FAB$W_MRS 


Maximum record size. 

FAB$B_ORG 


File organization. 

FAB$B_RAT 


Record attributes; used as output field except 
for process-permanent files with print file 
format. 

FAB$B_RFM 


Record format. 

FAB$L_SDC 


Spooling device characteristics. 

FAB$B_SHR 


File sharing. 

FAB$L_STS 


Completion status code (also returned in 
register 0). 

FAB$L_STV 


Status value (contains the I/O channel 
number if the operation is successful). 

FAB$L_XAB 


Next XAB address. 


XABALL 

Allocation XAB; see Chapter 8. 


XABDAT 

Date and time XAB; see Chapter 9. 


XABFHC 

File header characteristics XAB; see 

Chapter 10. 


XABITM 

Item list XAB; see Chapter 11. 


XABKEY 

Key definition XAB; see Chapter 13. 


XABPRO 

Protection XAB; see Chapter 14. 


XABRDT 

Revision date and time XAB; see Chapter 15. 


XABSUM 

Summary XAB; see Chapter 17. 


RMS-62 







VMS RMS Services 

$OPEN 


Using the Name Block for Opening Files 

Table RMS-31 and Table RMS-32 list the NAM block fields (further described 
in Chapter 6) used as input and output for the Open service (provided that 
the NAM block address field is specified in the FAB). 


Table RMS-31 Open Service NAM Block Input Fields 


Field Name 

Option 

Description 

NAM$W_DID’ 


Directory identification (input only if 
the FAB$L_FOP field FAB$V_NAM 
option is set). 

NAM$T_DVI' 


Device identification (input only if 
the FAB$L_FOP field FAB$V_NAM 
option is set). 

NAM$L_ESA 


Expanded string area address. 

NAM$B_ESS 


Expanded string area size. 

NAM$W_FID' 


File identification (input only if the 
FAB$L_FOP field FAB$V_NAM 
option is set). 

NAM$B_NOP 


NAM block options. 


NAM$V_PWD 

Password: indicates that a password 
contained in a DECnet access 
control string, if present in a file 
specification, is to be left unaltered 
in the expanded and resultant strings 
(instead of being replaced by the 
word "password"). 


NAM$V_NOCONCEAL 

Do not conceal device name: 
indicates that when a concealed 
device logical name is present, the 
concealed device logical name is to 
be replaced by the actual physical 
device name in the resultant string. 

NAM$L_RLF 


Related file NAM block address. 


NAM$B_RSL 

Related file NAM block resultant 
string length. 


NAM$L_RSA 

Related file NAM block resultant 
string address. 


NAM$L_FNB 

Related file NAM block file name 
status bits. 

NAM$L_RSA 


Resultant string area address. 

NAM$B_RSS 


Resultant string area size. 

^This field is not supported for DECnet operations. 
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Table RMS-32 Open Service NAM Block Output Fields 


Field Name 

Description 

NAM$W_DID’ 

Directory identification. 

NAM$T_DVr 

Device identification. 

NAM$B_ESL 

Expanded string length. If the NAM$L_ESA and NAM$B_ESS 
fields are nonzero, and if the FAB$L_FOP field FAB$V_NAM 
option Is clear or the NAM$W_DID and NAM$W_FID fields 
are 0 on Input, the expanded file specification string Is copied 
to the buffer specified by the NAM$I_ESA field. 

NAM$W_FID’ 

File identification. 

NAM$L_FNB 

File name status bits. 

NAM$B_RSL 

Resultant string length. If the NAM$I_RSA field and the 

NAM$B_RSS field are nonzero, and if the FAB$V_NAM bit Is 
clear or the NAM$W_FID field is zero when you invoke the 
Open service, the resultant file specification is copied to the 
buffer specified by the NAM$I_RSA field. 

^This field is not supported for DECnet operations. 


The NAM block file specification string descriptors can be used to identify 
individual components of the expanded or resultant file specification. These 
fields include the following: 



• NAM$B_NODE and NAM$L_NODE 

• NAM$B_DEV and NAM$L_DEV 

• NAM$B_DIR and NAM$L_DIR 

• NAM$B_NAME and NAM$L_NAME 

• NAM$B_TYPE and NAM$L_TYPE 

• NAM$B_VER and NAM$L_VER 

For additional information about these descriptors, see Chapter 6. 

RETURN 

The following condition values are described 

in Appendix A: 

VALUES 

RMS$_ACC 

RMS$_ACS 

RMS$_ACT 


RMS$_AID 

RMS$_ATR 

RMS$_BLN 


RMS$_BUG_DAP 

RMS$_BUG_DDI 

RMS$_CHN 


RMS$_COD 

RMS$_CRMP 

RMS$_DEV 


RMS$_DIR 

RMS$_DME 

RMS$_DNA 


RMS$_DNF 

RMS$_DNR 

RMS$_DVI 


RMS$_ENQ 

RMS$_ENV 

RMS$_ESA 


RMS$_ESS 

RMS$_EXP 

RMS$_FAB 


RMS$_FLK 

RMS$_FNA 

RMS$_FNF 

RMS-64 
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RMS$_FOP 

RMS$_IFA 
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RMS$_IFI 

RMS$_IMX 

RMS$_IRC 

RMS$_KNM 

RMS$_KSI 

RMS$_LNE 

RMS$_NAM 

RMS$_NET 

RMS$_NETFAIL 

RMS$_NOD 

RMS$_NORMAL 

RMS$_OK_NOP 

RMS$_ORG 

RMS$_PLG 

RMS$_PLV 

RMS$_PRV 

RMS$_QUO 

RMS$_RAT 

RMS$_REF 

RMS$_RLF 

RMS$_RPL 

RMS$_RSS 

RMS$_RST 

RMS$_RUNDOWN 

RMS$_SHR 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPERSEDE 

RMS$_SUPPORT 

RMS$_SYN 

RMS$_SYS 

RMS$_TYP 

RMS$_UPI 

RMS$_VER 

RMS$_WLK 

RMS$_XAB 
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SPARSE 

The Parse service analyzes the file specification string and fills in various 
NAM block fields. 

FORMAT 

SYSSPARSE fab [,[err] [,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 


ARGUMENTS 


fab 

VMS usage: 
type: 
access: 
mechanism: 


fab 

longword (unsigned) 

modify 

by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Parse service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: 
type: 
access: 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


The functions of the Parse service are performed automatically as part of the 
Open, Create, and Erase services. One special purpose of the Parse service is 
to prepare the FAB and NAM blocks for wildcard character processing to be 
used in the Search service. If wildcard characters, search list logical names, 
or a node name are present in the file specification, VMS RMS allocates 
internal data structures (including a device channel) to store the context 
for subsequent searches. This space is released when the Search service 
encounters a no-more-files condition (in which case an RMS$_-NMF error 
status is returned) or when another Parse service is performed using the same 
FAB and NAM blocks. To release this space, use a Parse service that specifies 
the NAM$B_-NOP field NAM$V_SYNCHK option and sets the FAB$B_DNS 
and NAM$L_RLF fields to zero. 

Note that the file must be closed before you invoke the Parse service 
(FAB$W_IFI must be 0). 

By default, the Parse service assigns a channel to the device and does a 
lookup of the directory in addition to analyzing the file specification and 
filling in the NAM block fields. To request a Parse service without I/O, 
specify the NAM$B.^NOP field NAM$V_SYNCHK option. The result of 
a Parse service without I/O cannot be used as input to subsequent Search 
services. 

Table RMS-33 and Table RMS-34 list the fields in both the FAB and NAM 
block that the Parse service uses as input and output. In addition, the string 
component descriptors are filled in by VMS RMS as output from the expanded 
string (see Chapter 6). 

The expanded file specification string is moved to the buffer described by 
the expanded string area address (NAM$L—ESA) and size (NAM$B_ESS) 
fields of the NAM block (only if both fields are nonzero). The NAM$L_ESA 
and NAM$B_ESS fields must be specified (nonzero) for wildcard character 
processing. 

Table RMS-33 lists the control block fields read as input by the Parse service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-33 
Field Name 

FAB$L_DNA 

FAB$B_DNS 

FAB$L_FNA 

FAB$B_FNS 

FAB$L_FOP 


FAB$W_IFI 

FAB$L_NAM 

NAM$L_ESA 


Parse Service FAB and NAM Block Input Fields 

Option Description 

Default file specification string. 

Default file specification string size. 
File specification string address. 

File specification string size. 

File-processing option, FAB$V_OFP. 
Output file parse: indicates that VMS 
RMS uses only the file name and file 
type fields of a related file resultant 
string whose address is contained in 
the NAM$L_RSA field. 

Internal file Identifier (must be zero). 
Name block address. 

Expanded string area address. 
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Table RMS-33 (Cont.) Parse Service FAB and NAM Block Input 

Fields 


Field Name Option 

NAM$B_ESS 

NAM$B_NOP 

NAM$V_NOCONCEAL 


NAM$V_PWD 


NAM$V_SYNCHK 

NAM$L_RLF 

NAM$L_RSA 

NAM$B_RSL 


Description 

Expanded string area size. 

NAM block options. 

Do not conceal device name: indicates 
that when a concealed device logical 
name Is present, the concealed device 
logical name is to be replaced by the 
actual physical device name in the 
expanded string. 

Password: Indicates that a password 
contained in a DECnet access control 
string. If present in a file specification, 
is to be left unaltered in the expanded 
and resultant strings (Instead of being 
replaced by the word "password”). 

Performs Parse service with no I/O. 
Related file NAM block address. 

Related file NAM block resultant string 
area address. 

Related file NAM block resultant string 
length. 


NAM$L_FNB Related file NAM block file name 

status bits. 


service. 



Table RMS-34 

Parse Service FAB and NAM Block Output Fields 

Field Name 

Description 

FAB$L_DEV 


Device characteristics (unless you select the NAM$V_ 
SYNCHK option). 

FAB$L_SDC 


Secondary device characteristics (unless you select the 
NAM$V_SYNCHK option). 

FAB$L_STS 


Completion status code (also returned in register 0). 

FAB$L_STV 


Status value. 

NAM$B_DEV 


Address of file specification device descriptor. 

NAM$L_DEV 


Size of file specification device descriptor. 

NAM$W_DID’ 


Directory Identification (unless you select the NAM$\/_ 
SYNCHK option). 

NAM$B_DIR 


Address of file specification directory descriptor. 

NAM$L_DIR 


Size of file specification directory descriptor. 


^This field Is not supported for DECnet operations. 
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Table RMS-34 (Cent.) Parse Service FAB and NAM Block Output 

Fields 


Field Name 

Description 

NAM$T_DVI’ 

Device identification (unless you select the NAM$V_ 
SYNCHK option). 

NAM$B_ESL 

Expanded string length. 

NAM$W_FID’ 

File identification (zeroed). 

NAM$L_FNB 

File name status bits: contains information about the 
parse results. 

NAM$B_NAME 

Address of file specification name descriptor. 

NAM$L_NAME 

Size of file specification name descriptor. 

NAM$B_NODE 

Address of file specification node descriptor. 

NAM$L_NODE 

Size of file specification node descriptor. 

NAM$B_RSL 

Resultant string length (zeroed). 

NAM$B_TYPE 

Address of file specification type descriptor. 

NAM$L_TYPE 

Size of file specification type descriptor. 

NAM$B_VERSION 

Address of file specification version descriptor. 

NAM$L_VERSION 

Size of file specification version descriptor. 

NAM$L_WCC 

Wildcard context. 

^This field is not supported for DECnet operations. 


The following condition values 

are described in Appendix A: 

RMS$_ACS 

RMS$_BLN 

RMS$_BUG_DDI 

RMS$_CDA 

RMS$_CHN 

RMS$_DEV 

RMS$_DIR 

RMS$_DME 

RMS$_DNA 

RMS$_DNF 

RMS$_DNR 

RMS$_ESA 

RMS$_ESS 

RMS$_FAB 

RMS$_FNA 

RMS$_FNM 

RMS$_IFI 

RMS$_LNE 

RMS$_NAM 

RMS$_NOD 

RMS$_NORMAL 

RI\/IS$_QUO 

RMS$_RLF 

RMS$_RUNDOWN 

RMS$_STR 

RMS$_SUC 

RMS$_SYN 

RMS$_TYP 

RMS$_VER 

RMS$_WCC 
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The Put service inserts a record into a file. 

FORMAT 

SYSSPUT rab [4err][,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Put service call. The rab argument is the address of the RAB control 
block. 

err 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 

DESCRIPTION 

The Put service usually adds records to the logical end of a sequential file. 

For relative files, it may add records to the logical end of the file or it may 
insert new records in cells formerly occupied by deleted records. VMS RMS 
directs the Put service where to insert the record using the contents of the 
record's primary key field. 
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Inserting Records into Sequential Files 

When using sequential record access mode to process sequential files, you 
usually insert records at the end of the file only. The records to be inserted 
cannot be larger than the maximum length that was specified when the file 
was created. 

You can use random access by relative record number mode and the update-if 
record-processing option (RAB$V_UIF) to insert fixed-length records into a 
sequential file residing on a disk device. 

VMS RMS also provides for establishing the logical end of the file when two 
or more processes are doing shared write operations. For example, assume 
that processes A and B are sharing a sequential file and each process is putting 
data into the file. Process A puts a record at the end of the file and intends to 
put another record at the new end-of-file location. However, before process A 
can put the next record in the file, process B gains access to the file and puts 
a record at the end of the file. In order to ensure that the next record from 
process A does not overwrite the record just inserted by process B, VMS RMS 
updates process A's write pointer to the new end-of:file position. That is, the 
location immediately following the location of process B's record. 

The truncate-on-put option (RAB$V_TPT) can be used with sequential files. 
This option lets you add records at locations other than the logical end of 
the file. When you add a record using the truncate-on-put option, the file is 
automatically truncated, effectively deleting all data between the new record 
(logical end of the file) and the physical end of the file. If you try to use this 
option without having truncate access, VMS RMS rejects the operation and 
issues a file access error (RMS$_FAC). 

For stream format files, VMS RMS writes the contents of the user's buffer into 
the file beginning at the current entry position. If the last byte in the buffer 
is not a terminator, VMS RMS automatically adds the appropriate terminator. 
For stream format, the terminator is CRLF (carriage return character followed 
immediately by a line feed character). 

Mailboxes may be used to synchronize activity between processes. Usually, 
a Put service to a mailbox does not conclude until another accessor reads the 
record. If you select the timeout option (RAB$V_TMO) and specify a timeout 
period of 0, the Put service does not wait for another accessor to read the 
record. 

At the conclusion of the Put service, the RAB$L_STV field contains the 
process identification (PID) of the process that read the record. 

Inserting Records into Relative Files 

When processing relative files, you can use either sequential or random access 
by key mode. Records cannot be larger than the size specified at file creation 
time, and the record's relative record number must not exceed the maximum 
record number established for the file. Usually, if the target record cell for 
a Put service contains a record, a record-already-exists error (RMS$_REX) is 
returned as the completion status (RAB$L—STS). If you specify the update-if 
(RAB$V_UIF) record option, VMS RMS overwrites the existing record instead 
of returning an error message. If you try to use the update-if option but do 
not have update access, VMS RMS rejects the operation and issues a file 
access error (RMS$ JAC). 
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Inserting Records into Indexed Files 

In an indexed file, you can use sequential access or random access by key 
mode. When sequential access is used to insert records, the primary key 
value of the record to be inserted must be consistent with the specified sort 
order of the file. That is, the key must be greater than or equal to the primary 
value of the previous record if ascending sort order is specified. If descending 
sort order is specified, the key must be less than or equal to the primary key 
value of the previous record. 

The records cannot be larger than the size established when the file was 
created if a maximum length was specified. Each record written must contain 
a primary key, but the records do not have to contain alternate keys. If 
alternate keys are partially or completely missing because of the record length 
limitation, VMS RMS does not make an entry for the record in the associated 
alternate index. Put services to an indexed file do not require a separate key 
value or key of reference. By examining the contents of the primary key in 
the record, VMS RMS determines where to insert the record. 

When inserting a record into an indexed file, VMS RMS compares the key 
values in the record with the key values of records previously inserted into 
the file to determine whether or not the new record's key value duplicates 
any existing key values. If the record duplicates a key value in an index 
where duplication is not allowed, VMS RMS rejects the operation with an 
RMS$_DUP error code. Where duplicate keys are allowed, VMS RMS inserts 
the record. 

Records with duplicate keys are inserted in chronological order; that is, VAX 
RMS inserts each record having duplicate keys at the end of a "chain" of 
identically keyed records so that newer records are stored closer to the end of 
the file regardless of sort order. 

If you specify the update-if (RAB$V_UIF) option when duplicates are not 
allowed on the primary key, VMS RMS overwrites the existing record 
with the same primary key value, rather than returning a duplicate record 
error (RMS$_DUP). This gives the appearance of an Update service being 
performed on the existing record. Alternate key values are modified to reflect 
the newly inserted record. 

To use the RAB$V_UIF option, you must have update access to the file. If 
update access to the file is not permitted, the Put service (which becomes an 
Update service when this option is selected) fails, and VMS RMS returns a 
file access error (RMS$_FAC). 

Be careful when invoking the PUT service with the RAB$V_UIF option and 
automatic record locking for a shared file. The Put service, unlike the Update 
service, momentarily releases record locks previously applied by a Get or 
Find service, until the PUT service is converted into an Update service. This 
could allow another record stream to delete or update the record between the 
invocation of the Put service and the conversion to an Update service. To 
avoid this complication, you should use the Update service instead of the Put 
service with the update-if option to update an existing record in a file-sharing 
situation. 

The record address field (RAB$L_RBF) and the record size field (RAB$W_ 
RSZ) are required inputs to the Put service, and some Put service options 
require additional fields. 

A successful Put service returns the record file address (RFA) in the RAB$W-.- 
RFA field. 
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Table RMS-35 lists the control block fields read as input by the Put service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-35 

Put Service RAB Input Fields 

Field Name 

Option or 

XAB Type 

Description 

RAB$W_ISI 


Internal stream Identifier (required). 

RAB$L_KBF 


Key buffer address (used as input only with 
random access by relative record number 
mode). 

RAB$B_KSZ 


Key size (used only if RAB$B_RAC is KEY 
and the file Is a relative file). 

RAB$B_RAC 


Record access mode (SEQ, KEY)\ 

RAB$L_RBF 


Record buffer address. 

RAB$L_RHB 


Record header buffer (applies only to 
variable with fixed control records). 

RAB$W_RSZ 


Record size. 

RAB$L_ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Put services 
asynchronously. 


RAB$V_CCO^ 

Cancel CTRL/0: guarantees that terminal 
output is not discarded if the operator 
enters CTRL/0. 


RAB$V_LOA 

Load: specifies that buckets are to be 
loaded according to the fill size established 
at file creation time. 


RAB$V_REA^ 

Lock for read: allows other users read 
access to the record. This is not valid for 
relative files. 


RAB$V_RLK3 

Read of locked record allowed: specifies 
that a user who locks a record for 
modification is allowing the locked record 
to be read by other accessors. 


rab$v_tmo2 

Timeout: indicates that the content of the 
timeout period field (RAB$B_TMO) is to be 
used. 


RAB$V_TPT 

Truncate-on-put: specifies that a Put 
service with a record accessed sequentially 
can occur at any point In the file, truncating 
the file at that point. 


RAB$V_UIF 

Update-lf: converts a Put service to a 
record that already exists to an Update 
service. 


^The default for the RAB$B_RAC field is RAB$C_SEQ. 
^This field Is not supported for DECnet operations. 


^This option is meaningless unless you specify manual unlocking. 
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Table RMS-35 (Cont.) Put Service RAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 


RAB$V_ULK 

Manual unlocking: specifies that records 
cannot be automatically unlocked. 


RAB$V_WBH 

Write behind: two buffers are allocated to 
allow multibuffering. 


RAB$V_WAT 

Wait: if record is locked, wait until it is 
available (applies to relative files). 

RAB$B_TMO’ 


Timeout period: a value of zero indicates 
that VMS RMS should not wait to complete 
a Put service (applies to mailbox devices 
only). 

^The default for the RAB$B_RAC field 

is RAB$C_SEQ. 


Table RMS-36 lists the control block fields written as output by the Put 
service. 


Table RMS-36 Put Service RAB Output Fields 


Field Name 

Option or 
XAB Type 

Description 

RAB$L_BKT 


Bucket code: set to the relative record number 
for sequential access to relative files. 

RAB$W_RFA 


Record file address. 

RAB$L_STS 


Completion status code (also returned in 
register 0). 

RAB$L_STV 


Status valueV 


^On the successful completion of a Put service to a record-oriented device, the RAB$L_ 
STV field contains the second longword of the I/O status block. See the VMS I/O User's 
Reference Manual: Part I in the VMS I/O User's Reference Volume for details on specific 
devices. 


RETURN The following condition values are described in Appendix A: 


VALUES 

RMS$_ACT 

RMS$_BLN 

RMS$_BUG 


RMS$_BUG_DAP 

RMS$_CDA 

RMS$_CHK 


RMS$_CONTROLC 

RMS$_CONTROLO 

RMS$_CONTROLY 


RMS$_DME 

RMS$_DNR 

RMS$_DUP 


RMS$_ENQ 

RMS$_EXT 

RMS$_FAC 


RMS$_FTM 

RMS$_FUL 

RMS$_IBF 


RMS$_IDX 

RMS$_IOP 

RMS$_IRC 


RMS$_ISI 

RMS$_KBF 

RMS$_KEY 
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RMS$_KSZ 

RMS$_MRN 

RMS$_NEF 

RMS$_NET 

RMS$_NETFAIL 

RMS$_NORMAL 

RMS$_OK_ALK 

RMS$_OK_DUP 

RMS$_OK_IDX 

RMS$_PENDING 

RMS$_PLG 

RMS$_RAB 

RMS$_RAC 

RMS$_RBF 

RMS$_RER 

RMS$_REX 

RMS$_RHB 

RMS$_RLK 

RMS$_RPL 

RMS$_RRV 

RMS$_RSA 

RMS$_RSZ 

RMS$_RVU 

RMS$_SEQ 

RMS$_SQO 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 

RMS$_SYS 

RMS$_TRE 

RMS$_WBE 

RMS$_WER 

RMS$_WLK 

RMS$_WPL 
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$READ 

The Read service retrieves a specified number of bytes from a file 
(beginning on a block boundary) and transfers them to memory. A Read 
service using block I/O can be performed on any file organization. 

FORMAT 

SYSSREAD rab [,[err] [,suc]] 


RETURNS 


ARGUMENTS 


VMS usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 


tab 

VMS usage: 
type: 
access: 
mechanism: 


rab 

longword (unsigned) 

modify 

by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Read service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


To use the Read service, you must do the following: 

1 Supply a buffer area into which VMS RMS is to transfer data (user record 
area address field, RAB$L_-UBF). 

2 Indicate the number of bytes to be transferred (user record area size field, 
RAB$W_USZ). 

3 Indicate the first virtual block number (VBN) for the transfer (bucket 
number field, RAB$L-^BKT). If the value for the VBN is 0, the transfer 
starts with the block indicated by the NBP (Next Block Pointer). 

Table RMS-37 lists the control block fields read as input by the Read service. 

For additional information on the fields accessed by this service, see Part II. 


Table RMS-37 Read Service RAB Input Fields 


Field Name 

Description 

RAB$L_BKT 

Bucket number: must contain the virtual block number of the 
first block to read. When this field has a value of 0, then the 
next block is read. 

RAB$W_ISI 

Internal stream identifier. 

RAB$L_ROP 

Record-processing option, ASY (RAB$V_ASY). Asynchronous: 
performs Read services asynchronously. 

RAB$L_UBF 

User record buffer address. For block I/O, alignment of the 
user's record buffer on a page or at least a quadword boundary 
may improve performance. 

RAB$W_USZ 

User record area size: indicates the length of the transfer. In 
bytes ^. 

^Certain devices require that an even number of bytes be transferred. For further details, 
see the VMS I/O User's Reference Manual: Part 1 in the VMS I/O User's Reference 
Volume. 

Table RMS-38 lists the control block fields written as output by the Read 

service. 


Table RMS- 

■38 Read Service RAB Output Fields 

Field Name 

Description 

RAB$L_RBF 

Record address. 

RAB$W_RFA 

Record file address. 

RAB$W_RSZ 

Record size: indicates the actual number of bytes transferred. 

RAB$L_STS 

Completion status code (also returned in register 0). 

RAB$L_STV 

Status value. 
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RETURN 

The following condition values are described in Appendix A: 


VALUES 

RMS$_ACT 

RMS$_BLN 

RMS$_BUG_DAP 

RMS$_CDA 


RMS$_CONTROLC 

RMS$_CONTROLY 

RMS$_DME 

RMS$_DNR 


RMS$_EOF 

RMS$_FAC 

RMS$_FTM 

RMS$_IOP 


RMS$_ISI 

RMS$_NET 

RMS$_NETFAIL 

RMS$_ 

NORMAL 


RMS$_PBF 

RMS$_PENDING 

RMS$_RAB 

RMS$_RER 


RMS$_RSA 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 


RMS$_SUPPORT 

RMS$_USZ 

RMS$_SYS 

RMS$_WBE 

RMS$_TMO 

RMS$_UBF 
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SRELEASE 



The Release service unlocks the record specified by the contents of the 
record file address (RAB$W_RFA) field of the RAB. 

FORMAT 

SYSSRELEASE rab [,[err][,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 


ARGUMENTS 


rab 

VMS usage; 
type: 
access: 
mechanism: 


rab 

longword (unsigned) 

modify 

by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Release service call. The tab argument is the address of the RAB control 
block. 


err 


VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage: 
type: 
access; 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Release service unlocks a specified record (see also the discussion of the 

Free service). If the named record is not locked, VMS RMS returns a status 
code of RMS$_RNL.j 

Table RMS-39 lists the control block fields read as input and written as 
output by the Release service. For additional information on the fields 
accessed by this service, see Part II. 


Table RMS-39 Rjelease Service RAB Input and Output Fields 



Field Name 

Description 

Input 

RAB$W_ISI 

RAB$W_RFA 

Internal stream identifier (required). 

Record file address (required). 

Output 

RAB$L_STS 

RAB$L_STV 

Completion status code (also returned in register 0). 

Status value. 


RETURN 

VALUES 


The following condition values are described in Appendix A: 


RMS$_ACT RMS$_BLN 

RMS$_1SI RMS$_NET 

RMS$_PENDING RMS$_RAB 
RMS$_STR RMS$_SUC 


RMS$_BUG_DAP 

RMS$_NETFAIL 

RMS$_RNL 

RMS$_SUP 


RMS$_CDA 

RMS$_NORMAL 

RMS$_RSA 

RMS$_SUPPORT 
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SREMOVE 

The Remove service deletes a file name from a directory. It is the reverse 
of the Enter service. 

FORMAT 

SYSSREMOVE fab ^err] [,suc]] 

RETURNS 

VMS usage: cond—value 
type; longword (unsigned) 

access: write only 

mechanism: by value 


The value returned in RO is also returned in symbolic offset FAB$L—STS. 
Symbolic offset FAB$L_STV may contain additional status information. 


ARGUMENTS 


fab 

VMS usage; 
type: 
access: 
mechanism: 


fab 

longword (unsigned) 

modify 

by reference 


FAB control block whose contents are to be used as indirect arguments for 
the Remove service call. The fab argument is the address of the FAB control 
block. 


err 


VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 


VMS usage; 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Remove service searches for the first file name that matches the expanded 

name string and directory ID in the user's NAM block, and then it deletes 
the file name without deleting the actual file. The Remove service is similar 
to the Erase service, except that the Erase service also deletes the file after 
performing an impliciit Remove. Note that you must close the file before 
invoking the Remove service (that is, the value of FAB$W_IFI must be 0). 

The Remove service accepts wildcard characters and search lists, and it 
is usually preceded by a call to the Parse service in order to fill in the 
appropriate fields of the NAM block. Because the Remove service returns 
the wildcard context held of the NAM block (NAM$L_WCC), the Remove 
service can be used on multiple successive calls in order to remove successive 
file names that match a wildcard file specification. 

Be careful when you mix calls to the Search and Remove services. For 
example, assume you invoke the following service sequence: 

• PARSE 

• SEARCH 

• REMOVE 

• SEARCH 

• REMOVE 

> 

VMS RMS responds by doing the following: 

1 Searches for the first file specification that matches the expanded name 
string 

2 Searches for and removes the second file specification 

3 Searches for the third file specification 

4 Searches for and removes the fourth file specification 

If you want to remove the directory entry of a file and you have that file's 
ID, then you can improve the speed of the Remove service by specifying the 
NAM bit in the FAB$L_FOP field. In order to do this properly, you must first 
parse the name of the file specification (to clear the NAM$W_FID field), place 
the correct FID in the NAM block, and then perform the Remove service. 

The Remove service is not supported for DECnet operations for remote file 
access between two VMS systems. 

Table RMS-40 lists tl^e control block fields read as input by the Remove 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS-40 

Remove Service FAB and NAM Block Input Fields 

Field Name 

Description 

FAB$L_FOP’ 

File-processing option, FAB$V_NAM only. NAM block inputs: 
indicates that the NAM$W_FID field is used as input. 

FAB$W_IFI 

Internal file identifier (must be zero). 


^This field is not supported for DECnet operations. 
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Table RMS-40 (Cont.) Remove Service FAB and NAM Block Input 



Fields 

Field Name 

Description 

FAB$L_NAM 

NAM$W_DID’ 

Name block address. 

Directory identification; identifies the directory from which the 
file is to be removed. 

NAM$T_DVI’ 

Device identification; identifies the device containing the 
directory from which the file is to be removed. 

NAM$L_ESA 

Expanded string area address specifying the name, type, and 
version of the file to be removed. 

NAM$B_ESL 

NAM$W_FID’ 

Expanded string length. 

File identification: if nonzero and FAB$I_FOP field FAB$V_ 

NAM bit is set in the input FAB, the first file in the directory 
with this file identification is removed. 

NAM$L_FNB 

NAM$L_RSA 

File name status bits (wildcard character bits only). 

Resultant string area address: specifies the name, type, and 
version number of the last file removed (required for wildcard 
character processing). 

NAM$B_RSL 

NAM$B_RSS 

NAM$L_WCC 

Resultant string length. 

Resultant string area size. 

Wildcard character context value. 


This field is not supported for DECnet operations. 


Table RMS-41 lists the control block fields written as output by the Remove 
service. 

Table RMS-41 Remove Service FAB and NAM Block Output Fields 


Field Name 

Description 

FAB$L_STS 

FAB$L_STV 

NAM$B_RSL 

Completion status code (also returned in register 0). 

Status value. 

Resultant string length. 


NAM$I_WCC Wildcard context value 


The resultant string is moved to the buffer described by the NAM$L_RSA 
and NAM$B_RSS fields (only if both fields are nonzero on input). 
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RETURN 

The following condition values are described in Appendix A: 

VALUES 

RMS$_BLN 

Rk/IS$_CDA 

RMS$_CHN 

RMS$_DEV 


RMS$_DME 

rIms$_dnf 

1 

RMS$_DNR 

RMS$_DVI 


RMS$_ESA 

F{MS$_ESL 

RMS$_FAB 

RMS$_FNF 


RMS$_IFI 

RMS$_NAM 

RMS$_NMF 

RMS$_NORMAL 


RMS$_PRV 

Hms$_rmv 

RMS$_RSL 

RMS$_RSS 


RMS$_RST 

RjMS$_STR 

RMS$_SUC 

RMS$_SUP 


RMS$_SUPPORT 

RMS$_WLK 

RjMS$_SYS 

RMS$_WCC 

RMS$_WLD 
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SRENAME 

You can use this service to change the name, type, or version of a file, or 
to move a file to another directory by changing its directory specification. 
However, note that you cannot use this service to move a file to another 
device. 

FORMAT 

SYSSRENAME old-fab ,[err],[suc],new-fab 

RETURNS 

VMS usage; cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

old-fab 

VMS usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Rename service call. The old-fab argument is the address of the FAB control 
block that specifies the old file name. 

err 

VMS usage: ast_procedure 
type; procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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new-fab 

VMS usage: 
type: 
access: 
mechanism: 


fab 

longvyord (unsigned) 

modify 

by reference 


The new-fab argument is the address of the FAB control block that specifies 
the new file name. 


Note: If you invoke the Rjename service using the $RENAME macro and if 
you do not specify arguments, you must construct an additional field 
within your argumejnt list to contain the address of the FAB that specifies 
the new file name. This additional field is placed in the argument list 
following the field for the success completion routine (see Part I), and the 
argument count is s^t to 4. 


DESCRIPTION The Rename service jperforms the equivalent of two Parse services (old and 

new name), a Search service for the old directory, an Enter service to insert 
the new file name into the new directory, and a Remove service to delete the 
old file name from the old directory. 

Note that you must close the file before invoking the Rename service 
(FAB$W_IFI must be 0), and no wildcard character specifications are allowed. 
You can move a file from one directory to another using this service, but both 
directories must be on the same disk device. 

If the Rename service is successful, the new directory entry is created and the 
old entry is deleted. If the service fails, the old entry remains and the new 
entry is deleted. 

Table RMS-42 lists the fields in two FABs and two NAM blocks that the 
Rename service uses as input and output. In the table, these blocks are called 
FABl and NAMl for| the old entry, and FAB2 and NAM2 for the new entry. 
For output, FAB2 is not used, although it must be in writable memory. To 
check or signal the completion codes in FAB$L_STS and FAB$L__STV, use 
the first FAB (FAB1).| 

The resultant file spelcification string for each of the names (old and new) is 
placed in the buffer described by the NAM$L_RSA and NAM$B_RSS fields 
of the separate NAMj blocks (only if both fields are nonzero). 

Table RMS-42 lists the control block fields read as input by the Rename 
service. For additional information on the fields accessed by this service, see 
Part II. 
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Table RMS—42 Rename Service FAB and NAM Block Input Fields 


Control Block 

Field Name 

Description 

FAB1 and FAB2 

FAB$L_DNA 

Default file specification string address. 


FAB$B_DNS 

Default file specification string size. 


FAB$L_FNA 

File specification string address. 


FAB$B_FNS 

File specification string size. 


FAB$W_IFI 

Internal file identifier (must be zero). 


FAB$L_NAM 

Name block address. 

NAM1 and NAM2 

NAM$L_ESA 

Expanded string area address 
(must be nonzero). 


NAM$B_ESS 

Expanded string area size 
(must be nonzero). 


NAM$L_RLF 

Related file NAM block address. 


NAM$L_RSA 

Resultant string area address. 


NAM$B_RSS 

Resultant string area size. 

Related file NAM 

NAM$L_RSA 

Related file resultant string area address. 

blocks 


NAM$B_RSL 

Related file resultant string length. 


NAM$L_FNB 

Related file name status bits. 

Table RMS-43 lists the control block fields written as output by the Rename 

service. 

Table RMS-43 

Rename Service FAB and NAM Block Output Fields 

Control Block 

Field Name 

Description 

FAB1 

FAB$L_STS 

Completion status code (also 
returned in register 0). 


FAB$L_STV 

Status value. 

NAM1 and NAM2 

NAM$W_DID' 

Directory Identification. 


NAM$T_DVI’ 

Device identification. 


NAM$B_ESL 

Expanded string length. 


NAM$W_FID’ 

File identification. 


NAM$L_FNB 

File name status bits. 


NAM$B_RSL 

Resultant string length. 


NAM$L_WCC 

Wildcard context. 


'This field is not supported for DECnet operations. 
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RETURN 

VALUES 
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Services 


The following condhion values are described in Appendix A: 


RMS$_ACC 

RMS$_CDA 

RMS$_DIR 

RMS$_DNF 

RMS$_ENT 

RMS$_FAB 

RMS$_IDR 

RMS$_NAM 

RMS$_NMF 

RMS$_QUO 

RMS$_RMV 

RMS$_RUNDOWN 

RMS$_SUPPORT 

RMS$_TYP 


RMS$_BLN 

RMS$_CHN 

RMS$_DME 

RMS$_DNR 

RMS$_ESA 

RMS$FNA 

RMS$_IFI 

RMS$_NET 

RMS$_NORMAL 

RMS$_REENT 

RMS$_RSS 

RMS$_STR 

RMS$_SYN 

RMS$_VER 


RMS$_BUG_DDI 

RMS$_DEV 

RMS$_DNA 

RMS$_DVI 

RMS$_ESS 

RMS$_FNM 

RMS$_LNE 

RMS$_NETFAIL 

RMS$_PRV 

RMS$_RLF 

RMS$_RST 

RMS$_SUC 

RMS$_SYS 

RMS$_WLD 
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SREWIND 

The Rewind service sets the context of a record stream to the first record 
in the file. VMS RMS alters the context of the next record to indicate the 
first record as being the next record. 

FORMAT 

SYSSREWIND rab[,[err][,suc]] 

RETURNS 

VMS usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L _STV may contain additional status information. 

ARGUMENTS 

rab 

VMS usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Rewind service call. The rab argument is the address of the RAB control 
block. 

err 

VMS usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


RETURN 

VALUES 


The Rewind service implicitly performs the Flush and Free services, writing 
out all I/O buffers and releasing all locked records. This service is valid for 
all file organizations on disk volumes and for sequential files on tape volumes 
For indexed files, the key of reference field establishes the index to be used 
for subsequent sequential accesses. You cannot rewind a unit record device, 
such as a card reader, a mailbox, a printer, or a terminal. You cannot rewind 
indirectly accessed process-permanent files. Also, you cannot rewind a file 
that was opened with the FAB$L_FOP field FAB$V_SQO option set. 

Table RMS-44 lists the control block fields read as input by the Rewind 
service. For additional information on the fields accessed by this service, see 
Part 11. 


Table RMS-44 Rewind Service RAB Input Fields 

Field Name Description 

RAB$W_ISI Internal stream identifier (required). 

RAB$B_KRF Key of reference (used only with indexed files). 

RAB$I—ROP Record-processing option, RAB$V_ASY option only. 

Asynchronous: performs a Rewind service asynchronously. 


Table RMS-45 lists the control block fields written as output by the Rewind 
service. 

Table RMS-45 Rewind Service RAB Output Fields 

Field Name Description 

RAB$1—STS Completion status code (also returned in register 0). 

RAB$I—STV Status value. 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_B0F 

RMS$_DNR 

RMS$_KRF 

RMS$_PENDING 

RMS$_STR 

RMS$_SYS 


RMS$_ATR 

RMS$_BUG_DAP 

RMS$_DPE 

RMS$_NET 

RMS$_QUO 

RMS$_SUC 

RMS$_WBE 


RMS$_ATW 

RMS$_CDA 

RMS$_I0P 

RMS$_NETFAIL 

RMS$_RAB 

RMS$_SUP 

RMS$_WER 


RMS$_BLN 

RMS$_DME 

RMS$_ISI 

RMS$_NORMAL 

RMS$_RSA 

RMS$_SUPPORT 

RMS$_WLK 
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$SEARCH 

The Search service scans a directory file and fills in various NAM block 
fields. This service should be preceded by the Parse service, in order to 
initialize the NAM block appropriately. 

FORMAT 

SYSSSEARCH fab [,[err] [,suc]] 

RETURNS 

VMS usage; cond—value 
type; longword (unsigned) 

access; write only 

mechanism; by value 


The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS usage; fab 

type; longword (unsigned) 

access; modify 

mechanism; by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Search service call. The fab argument is the address of the FAB control block. 


err 

VMS usage; ast—procedure 
type; procedure entry mask 

access; call without stack unwinding 

mechanism; by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 

VMS usage; ast—procedure 
type; procedure entry mask 

access; call without stack unwinding 

mechanism; by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The basic functions of the Search service and the Parse service are performed 

automatically as part of the Open, Create, and Erase services. Note that you 
must close the file before invoking the Search service (FAB$WL-IFI must be 0). 

When called, the Search service scans the directory file specified by the 
directory identification (NAM$W—DID) field of the NAM block. It looks for 
an entry that matches the file name, type, and version number specified by 
the expanded string area address and expanded string length fields. Upon 
finding a match, VMS RMS returns the file name, type, and version number 
in the buffer described by the resultant string area address and size fields. 
VMS RMS also fills in the file identification field to enable a subsequent 
open-by-NAM-block operation. You can also use the Search service to obtain 
a series of file specifications whose names match a file specification that 
contains wildcard characters or search lists. 

The resultant file specification string is placed in the buffer described by 
the resultant string afea address (NAM$L_RSA) and size (NAM$B_RSS) 
fields of the NAM block (only if both fields are nonzero). The NAM$L_-.RSA 
and NAM$B_RSS fields must be specified (nonzero) for wildcard character 
processing. 

Table RMS-46 lists the control block fields read as input by the Search 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS—46 Search Service FAB and NAM Block Input Fields 

Field Name Option Description 


FAB$W_IFI 

FAB$L_NAM 

NAM$W_DID^ 

NAM$T_DVI^ 

NAM$L_ESA 

NAM$B_ESL 

NAM$L_FNB 

NAM$B_NOP 

NAM$V_PWD 


Internal file identifier (must be zero). 
Name block address. 

Directory identification of the 
directory to be searched. 

Device identification of device 
containing directory to be searched. 

Expanded string area address: 
specifies file name, type, and version 
of file. 

Expanded string length. 

File name status bits (wildcard 
character options only). 

NAM block options. 

Password; indicates that a password 
contained in a DECnet access 
control string, if present in a file 
specification, is to be left unaltered 
in the expanded and resultant strings 
(instead of being replaced by the 
word "password"). 


^This field is not supported for DECnet operations. 
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Table RMS-46 (Cont.) Search Service FAB and NAM Block Input 

Fields 


Field Name 

Option 

Description 


NAM$V_NOCONCEAL 

Do not conceal device name: 
indicates that when a concealed 
device logical name is present, the 
concealed device logical name is to 
be replaced by the actual physical 
device name In the resultant string. 


NAM$V_SRCHXABS 

Performs Display service on 
remote files (for output fields, see 
description of Display service). 

NAM$L_RSA 


Resultant NAM block string area 
address: specifies name, type, and 
version of last file found (required for 
wildcard character processing). 

NAM$B_RSS 


Resultant NAM block string area 
size. 

NAM$L_WCC 


Wildcard character context value. 


service. 

Table RMS-47 

Search Service FAB and NAM Block Output Fields 

Field Name 

Description 


FAB$L_STS 

FAB$L_STV 

Completion status code (also returned in register 0). 

Status value. 


NAM$B_DEV 

NAM$L_DEV 

NAM$B_DIR 

NAM$L_DIR 

NAM$W_FID' 

NAM$L_FNB 

NAM$B_NAME 

NAM$L_NAME 

NAM$B_NODE 

NAM$L_NODE 

NAM$B_RSL 

NAM$B_TYPE 

NAM$L_TYPE 

NAM$B_VERSION 


Address of file specification device descriptor. 
Size of file specification device descriptor. 
Address of file specification directory descriptor. 
Size of file specification directory descriptor. 

File identification. 

File name status bits (wildcard status bits only). 
Address of file specification name descriptor. 
Size of file specification name descriptor. 
Address of file specification node descriptor. 
Size of file specification node descriptor. 
Resultant string length. 

Address of file specification type descriptor. 

Size of file specification type descriptor. 

Address of file specification version descriptor. 


'This field is not supported for DECnet operations. 
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Table RMS-47 (Cpnt.) Search Service FAB and NAM Block Output 

Fields 

Field Name Description 

NAM$I—VERSION Size of file specification version descriptor. 

NAM$L_WCC Wildcard character context value. 


RETURN The following condition values are described in Appendix A: 


VALUES 

RMS$_ACS 

RMS$_BLN 

RMS$_CHN 

RMS$_DEV 


RMS$_DME 

RMS$_DNF 

RMS$_DNR 

RMS$_DVI 


RMS$_ESA 

RMS$_ESL 

RMS$_FAB 

RMS$_FND 


RMS$_FNF 

RMS$_IFI 

RMS$_NAM 

RMS$_NET 


RMS$_NETFAIL 

RMS$_NMF 

RMS$_NORMAL 

RMS$_NOVALPRS 


RMS$_PRV 

RMS$_RSL 

RMS$_RSS 

RMS$_RST 


RMS$_STR 

RMS$_SYS 

RMS$_SUC 

RMS$_WCC 

RMS$_SUP 

RMS$_SUPPORT 
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$SPACE 

The Space service lets you space (skip) a tape file forward or backward a 
specified number of blocks. 

FORMAT 

SYS$S PAC E rab [,[err] [, sue]] 

RETURNS 

VMS usage; cond—value 
type: longword (unsigned) 

access; write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Space service call. The rab argument is the address of the RAB control 
block. 

err 

VMS usage: ast_procedure 
type; procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage; ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Space service is intended primarily for use with magnetic tape files; the 

tape is skipped forward or backward the number of blocks specified in the 
bucket number field. (The size of each block on any tape is specific to that 
tape and is defined on the tape itself, not by VMS or VMS RMS.) If the value 
in this field is positive, the tape skips forward; if the value is negative, the 
tape skips backward. For disk files, the next block pointer (NBP) is updated 
to reflect the new sequential operation position. 

Table RMS-48 lists the control block fields read as input by the Space service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS—48 Space Service RAB Input Fields 


Field Name 

Description 

RAB$L_BKT 

Bucket code: indicates the number of blocks to space forward 
(positive value) or backward (negative value). 

RAB$W_ISI 

Internal stream identifier. 

RAB$L_ROP 

Record-processing option, RAB$V_ASY only. Asynchronous: 
performs Space services asynchronously. 

Table RMS-49 lists the control block fields written as output by the Space 
service. 

Table RMS- 

-49 Space Service RAB Output Fields 

Field Name 

Description 

RAB$L_STS 

Completion status code (also returned in register 0). 

RAB$L_STV 

Status value (the absolute number of blocks actually skipped; 
the value is always positive). 


RETURN The following condition values are described in Appendix A: 


VALUES 

RMS$_ACT 

RMS$_BLN 

RMS$_BOF 

RMS$_BUG 


RMS$_CDA 

RMS$_DME 

RMS$_DNR 

RMS$_DPE 


RMS$_EOF 

RMS$_IOP 

RMS$_ISI 

RMS$_NET 


RMS$_NETFAIL 

RMS$_NORMAL 

RMS$_PENDING 

RMS$_RAB 


RMS$_RSA 

RMS$_SUPPORT 

RMS$_STR 

RMS$_SYS 

RMS$_SUC 

RMS$_WBE 

RMS$_SUP 
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$TRUNCATE 



The Truncate service removes records from the end of a sequential file. 

FORMAT 

SYSSTRUNCATE rab [,[err] [,suc]] 

RETURNS 

VMS usage: cond—value 
type; longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS usage: rab 

type: longword (unsigned) 

access; modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Truncate service call. The rab argument is the address of the RAB control 
block. 

err 

VMS usage: ast_procedure 
type; procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 

sue 

VMS usage: ast_procedure 
type; procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 

DESCRIPTION 

You can only truncate a sequential file that is open for exclusive access. The 
file-sharing (FAB$B_SHR) field must be set or defaulted to NIL, and the file 
access (FAB$B_FAC) field must specify a truncate access (FAB$V_TRN). 
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The Truncate service deletes the record indicated as the current record, and all 
following records. You can only use this service immediately after successful 
execution of a Get or Find service (thereby setting the context of the current 
record). 

VMS RMS declares the logical end of file to be the starting record position 
for the truncation and then uses the end of file to establish the context of the 
next record. You can then add records to the file by issuing successive Put 
services. 

Table RMS-50 lists the control block fields read as input by the Truncate 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS-50 Truncate Service RAB Input Fields 


Field Name 

Description 

RAB$W_ISI 

RAB$L_ROP 

Internal stream identifier (required). 

Record-processing option, RAB$V_ASY only. Asynchronous: 
performs Truncate services asynchronously. 

Table RMS-51 lists the control block fields written as output by the Truncate 
service. 

Table RMS- 

-51 Truncate Service RAB Output Fields 

Field Name 

Description 

RAB$L_STS 

RAB$L_STV 

Completion status code (also returned in register 0). 

Status value. 


RETURN The following condition values are described in Appendix A: 


VALUES 

RMS$_ACT 

RMS$_ATR 

RMS$_ATW 

RMS$_BLN 


RMS$_BUG_DAP 

RMS$_CDA 

RMS$_CUR 

RMS$_DEADLOCK 


RMS$_DME 

RMS$_DNR 

RMS$_DPE 

RMS$_FAC 


RMS$_IOP 

RMS$_ISI 

RMS$_NET 

RMS$_NETFAIL 


RMS$_NORMAL 

RMS$_PENDING 

RMS$_RAB 

RMS$_RER 


RMS$_RSA 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 


RMS$_SUPPORT 

RMS$_SYS 

RMS$_WBE 

RMS$_WER 


RMS$_WLK 
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SUPDATE 


The Update service allows you to modify the contents of an existing 
record in a file residing on a disk device. 


FORMAT 

SYS$UPDATE rab [,[err] [,suc]] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Update service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage; 
type: 
access: 
mechanism: 


ast_procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


sue 


VMS usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The sue argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The record to be updated by the Update service must first be locked by this 

stream, using either a Find or Get service. When updating a record, you must 
use move mode (not locate mode); that is, you must supply a buffer. 

The record length for sequential files cannot change. For relative files with 
variable-length or variable with fixed-length control records, the length of the 
replacement record can be different from the length of the original record, but 
cannot be larger than the maximum size you set when you created the file. 

For stream format files, the Update service functions in the same manner as 
the Put service, with one exception. When using the Update service, you do 
not have to set the RAB$L_ROP field RAB$V_TPT option to update data in 
the middle of a file. 

For indexed files, the length of the replacement record written by the Update 
service may be different from the original record but RMS does not permit 
you to change the primary key. Each replacement record must be large 
enough to contain a complete primary key, but it does not have to contain all 
alternate keys. 

If an alternate key is partially or completely missing in the replacement 
record, the key must have the characteristic that the values can change; this is 
also true if the replacement record contains a key that was not present in the 
original record. 

Update operations to an indexed file do not require a key value or key of 
reference. Before writing the record, VMS RMS compares the key values 
(primary and alternate) in the replacement record with the key values of the 
original record already existing in the file. This comparison takes the defined 
characteristics of each key into account. For example, if a particular key is not 
allowed to change, VMS RMS rejects the operation with an RMS$_CHG error 
code if the replacement record contains an altered value in the associated key. 
Similarly, this comparison determines whether the replacement record would 
result in the presence of duplicate key values among records of the file. If 
duplicates would occur, VMS RMS verifies the defined characteristics for the 
keys being duplicated. If duplicates are not allowed for a particular key, VMS 
RMS rejects the operation with an RMS$_DUP error code. If duplicates are 
allowed, VMS RMS performs the operation. 

Subsequent sequential operations on a given index retrieve records with 
identical key values in the order in which the records were written. 

Table RMS-52 lists the control block fields read as input by the Update 
service. For additional information on the fields accessed by this service, see 
Part II. 

Table RMS—52 Update Service RAB Input Fields 
Field Name Option Description 


Internal stream identifier (required). 

Record buffer address. 

Record header buffer (applies only to variable 
with fixed control records). 

Record-processing options. 


RAB$W_ISI 

RAB$L_RBF 

RAB$L_RHB 

RAB$L_ROP 
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Table RMS-52 (Cont.) Update Service RAB Input Fields 


Field Name 

Option 

Description 

RAB$W_RSZ 

RAB$V_ASY 

RAB$V_WBH 

Asynchronous: performs Update services 
asynchronously. 

Write-locked: two buffers are allocated to 
allow multibuffering. 

Record size (required). 

Table RMS-53 lists the control block fields written as output by the Update 
service. 

Table RMS- 

-53 Update Service RAB Output Fields 

Field Name 

Option 



RAB$W_RFA Record file address. 

RAB$I_STS Completion status code (also returned in register 0). 

RAB$I STV Status value. 


RETURN 

The following condition values are described in Appendix A: 

VALUES 

RMS$_ACT 

RMS$_ATR 

RMS$_ATW 

RMS$_BLN 


RMS$_BUG 

RMS$_BUG_DAF 

’ RMS$_CDA 

RMS$_CHG 


RMS$_CHK 

RMS$_CUR 

RMS$_DME 

RMS$_DNR 


RMS$_DUP 

RMS$_ENQ 

RMS$_EXP 

RMS$_FAC 


RMS$_FTM 

RMS$_IBF 

RMS$_IDX 

RMS$_IOP 


RMS$_IRC 

RMS$_ISI 

RMS$_NET 

RMS$_NETFAIL 


RMS$_NORMAL 

RMS$_OK_DUP 

RMS$_OK_IDX 

RMS$_PENDING 


RMS$_PLG 

RMS$_RAB 

RMS$_RBF 

RMS$_RER 


RMS$_RHB 

RMS$_RNL 

RMS$_RPL 

RMS$_RRV 


RMS$_RSA 

RMS$_RSZ 

RMS$_RVU 

RMS$_STR 


RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 

RMS$_SYS 


RMS$_TRE 

RMS$_WBE 

RMS$_WER 

RMS$_WLK 


RMS$_WPL 
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$WAIT 


The Wait service suspends image execution until an asynchronous record 
service completes. Upon completion of the service, VMS RMS returns 
control to your program at the point following the Wait service call. 


FORMAT SYSSWAIT rab 


RETURNS 


ARGUMENTS 


VMS usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 


rab 

VMS usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Wait service call. The rab argument is the address of the RAB control 
block. It can be either the RAB whose I/O request is in progress or some 
other RAB. 


DESCRIPTION The Wait service takes no arguments to define entry points for user-written 

completion routines; the completion routines are specified by the service 
being awaited. 

Any completion routines specified on the operation being awaited are 
declared as ASTs before VMS RMS returns control. They are executed 
before the WAIT service completes unless ASTs are disabled. Completion 
routines are always executed as asynchronous system traps (ASTs). 

Table RMS-54 lists the control block fields read as input and written as 
output by the Wait service. For additional information on the fields accessed 
by this service, see Part II. 


Table RMS-54 Wait Service RAB Input and Output Fields 


Use 

Field 

Name 


Description 

Input 

RAB$W_ISI 

RAB$L_STS 

Internal stream identifier (required). 

Status completion code. 

Output 

RAB$L_STS 

Completion status code (also returned In register 0). 
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The following condition values are described in Appendix A: 

RMS$_BLN RMS$_CDA RMS$_ISI RMS$_NORMAL 

RMS$_RAB RMS$_STR RMS$_SUC 

The VMS RMS completion status codes for the Wait service are determined by 
the VMS RMS service being awaited, unless the address of the RAB specified 
for the wait is different from that specified for the awaited operation. In this 
case, RMS$_NORMAL is returned. 
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$WRITE 



The Write 

service transfers a user-specified number of bytes (beginning 

on a block 

boundary) to a VMS RMS file of any file organization. 

FORMAT SYSSWRITE 

rab i, [err] [,sue]] 

RETURNS VMS usage 

y. cond_ 

.value 

type: 

longword (unsigned) 

access: 

write 

only 

mechanism 

: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 

Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS rab 



VMS usage 

!: rab 


type; 

longword (unsigned) 

access: 

modif 

y 

mechanism 

: by reference 

RAB control block whose contents are to be used as indirect arguments for 

the Write service call 

. The rab argument is the address of the RAB control 

block. 



err 



VMS usage 

c ast—p 

rocedure 

type: 

procedure entry mask 

access: 

call without stack unwinding 

mechanism 

: by reference 

AST-level error completion routine that the service invokes if the operation 

is unsuccessful. The 

err argument is the address of the entry mask of this 

user-written 

1 completion routine. 

sue 



VMS usage 

: ast_p 

rocedure 

type: 

procedure entry mask 

access; 

call without stack unwinding 

mechanism 

: by reference 

AST-level success completion routine that the service invokes if the operation 

is successful 

1 . The sue argument is the address of the entry mask of this 

user-written 

completion routine. 
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DESCRIPTION 


You specify the number of bytes to be written by the Write service in the 
record size (RAB$W—RSZ) field of the RAB and the address of the buffer for 
the transfer in the record address (RAB$L_RBF) field. In the bucket number 
(RAB$L_BKT) field, you indicate the virtual block number of the first block 
to be written; if this number is 0, the transfer starts with the block indicated 
by the NBP. 

A sequential file is automatically extended if you write a block past the end 
of the currently allocated space when using block I/O (or record I/O). For 
sequential files, VMS RMS maintains a logical end of file to correspond to the 
last block and highest byte written within the block. For relative and indexed 
files, you must use the Extend service when using block I/O. 

Table RMS-55 lists the control block fields read as input by the Write service. 
For additional information on the fields accessed by this service, see Part II. 

Table RMS-55 Write Service RAB Input Fields 


Field Name Option Description 


RAB$L_BKT 


Bucket number: must contain the virtual block 
number of the first block to be written. 

RAB$W_ISI 


Internal stream identifier. 

RAB$L_RBF 


Record buffer address. For block I/O, 
alignment of the user's record buffer on a 
page or at least a quadword boundary may 
improve performance. 

RAB$L_ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Write services 
asynchronously. 


RAB$V_TPT 

Truncate on Put: specifies that a Write service 
truncate the file after the transferred data. 

RAB$W_RSZ 


Record size: indicates the transfer length, in 
bytes. ^ 


^Certain devices require that an even number of bytes be transferred. For further details, 
see the VMS I/O User's Reference Volume. 


Table RMS-56 lists the control block fields written as output by the Write 
service. 


Table RMS-56 Write Service RAB Output Fields 


Field Name 

Description 

RAB$W_RFA 

RAB$L_STS 

RAB$L_STV 

Record file address. 

Completion status code (also returned in register 0). 

Status value: contains the actual number of bytes transferred if 
an end-of-file error occurs. 
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RETURN The following condijtion values are described in Appendix A: 


VALUES RMS$_ACT 

RMS$_BLN 

RMS$_CONTROLC 

RMS$_DME 

RMS$_EXT 

RMS$_FUL 

RMS$_NET 

RMS$_PENDING 

RMS$_RSA 

RMS$_SUC 

RMS$_WBE 
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RMS$_ATR 

RMS$_ATW 

RMS$_BUG_DAP 

RMS$_CDA 

RMS$_CONTROLO 

RMS$_CONTROLY 

RMS$_DNR 

RMS$_EOF 

RMS$_FAC 

RMS$_FTM 

RMS$_IOP 

RMS$_ISI 

RMS$_NETFAIL 

RMS$_NORMAL 

RMS$_RAB 

RMS$_RBF 

RMS$_RSZ 

RMS$_STR 

RMS$_SUP 

RMS$_SUPPORT 

RMS$_WER 

RMS$_WLK 
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This appendix includes two tables: one is a listing of VMS RMS completion 
status codes ordered by the hexadecimal coding, and the other is a more 
descriptive listing ordered alphabetically. See Part III for a listing of the status 
codes applicable to individual VMS RMS services. 

This appendix lists completion status codes for the RMS Journaling product 
and some of the completion status codes for the SNA VMS Data Transfer 
Facility but does not provide details. See the VAX RMS Journaling Manual 
for an explanation of RMS Journaling status codes and the DECnet/SNA VMS 
Data Transfer Facility User's Guide for details of the SNA VMS Data Transfer 
Facility completion status codes. VMS RMS completion status error codes 
generally fall into one of four groups: 

• Programming errors 

• Program design errors 

• System environment errors 

• Operator/user errors 

Here is a brief description of each group: 

Error Group 
Programming Errors 

These errors are caused by incorrect programming and are usually detected 
during the early stages of developing and debugging a program that uses 
VMS RMS. Typical examples are missing values for required fields, referring 
to a RAB instead of a FAB, invalid address for a buffer^ and so forth. This 
type of error is generally self-explanatory and usually requires only a minor 
change to the program. 

Program Design Errors 

These errors are caused by more subtle errors that may rarely occur, 
particularly if asynchronous record I/O, multistreamed sharing, or shared 
files are involved. These errors may occur long after a program has been 
in use and could require either a major program revision or the addition of 
substantial error recovery code to handle the error conditions. Record-lock 
errors, resource-exhaustion errors, and record-stream-currently-active errors 
are typical progam design errors. 

System Environment Errors 

These errors include hardware errors and VMS RMS or other system software 
errors that are not caused by your program. You may need to add substantial 
defensive error-handling code or you may be able to run the program again 
without error. 

Operator/User Errors 

These errors include errors by the user of the program, such as not mounting 
a device before running the program, or typing an invalid file specification. 
As with system environment errors, you may need to add substantial 
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defensive error-handling code or simply reprompt the user for the correct 
information or user action. 

These are conditions in which completion status codes may not be returned 
as expected: 

• The completion status codes that apply to the Close service do not include 
errors introduced by the FAB$Y__SCF option and the FAB$V_SPL option. 
If the request is serviced successfully, then a success completion code is 
returned, even if the request is found to be in error by the job controller 
process. 

• The Wait service has unique errors. This service can return any status 
code of the awaited operation. 

• Errors associated with output operations may not necessarily be reported 
as the status of a particular operation because modified I/O buffers are 
not always written out immediately. Such errors are reported as the 
status of a subsequent operation, which may be an input, output, or 
control operation. 

Procedures for signaling VMS RMS completion status codes are discussed 
in Chapter 2 for VAX languages other than VAX MACRO. VAX MACRO 
users should refer to Chapter 3 and the example programs in Chapter 4 for 
information on signaling VMS RMS errors. Note that certain errors may not 
be signaled using the FAB$L_STS/FAB$L_STV or RAB$L_.STS/RAB$L_ 
STV fields; these are denoted below and in Chapter 2. 

A description of each completion status code is listed in this appendix. When 
an error description indicates that the STV field should be examined for a 
secondary status code, this usually indicates a non-VMS RMS completion 
status (such as an ACP completion status). Non-VMS RMS errors are not 
described in this document; see the VMS System Messages and Recovery 
Procedures Reference Volume. 

Please note that when you submit an SPR, you should also provide a 
magnetic tape copy of the file causing the error. 

When using the debugger, use the debug command EXAMINE/CONDITION 
to view the message corresponding to the value in RO or the STS field or the 
STV field. For example, you can view the error codes in the STS and STV 
fields of the FAB at symbolic address (label) MYFAB when debugging a VAX 
MACRO program by entering the following commands: 

DBG> EXAMINE/CONDITION MYFAB+FAB$L_STS 
DBG> EXAMINE/CONDITION MYFAB+FAB$L_STV 

For additional information about the debugger, see the VMS Debugger Manual. 

Table A-1 lists the codes by hexadecimal values and includes a very brief 
description of each code. Table A-2 is ordered alphabetically and provides 
more detailed descriptions of the codes. 
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Table A-1 

Completion Status Hexadecimal Values and Codes 

Hex Value 

Status Code 

Message Text 

00010001 

RMS$_SUC 

Normal successful completion (same as RMS$_NORMAL) 

00010001 

RMS$_NORMAL 

Normal successful completion (same as RMS$_SUC) 

00010609 

RMS$_CONTROLO 

Operation completed under CTRL/0 

00010611 

RMS$_CONTROLY 

Operation completed under CTRL/Y 

00010619 

RMS$_CREATED 

File did not exist—was created 

00010631 

RMS$_SUPERSEDE 

Created file superseded existing version 

00010651 

RMS$_CONTROLC 

Operation completed under CTRL/0 

00010679 

RMS$_FILEPURGED 

Created file deleted oldest version 

00018009 

RMS$_PENDING 

Asynchronous operation not yet completed 

00018011 

RMS$_OK_DUP 

Record Inserted had duplicate key 

00018019 

RMS$_0K_IDX 

Index update error occurred 

00018021 

RMS$_OK_RLK 

Record locked but read anyway 

00018029 

RMS$_OK_RRL 

Record locked against read but read anyway 

00018031 

RMS$_KFF 

Known file found 

00018039 

RMS$_OK_ALK 

Record is already locked 

00018041 

RMS$_0K_DEL 

Deleted record successfully accessed 

00018049 

RMS$_0K_RNF 

Nonexistent record successfully accessed 

00018051 

RMS$_OK_LIM 

Retrieved record exceeds specified key value 

00018059 

RMS$_OK_NOP 

XAB not filled In for block I/O 

00018061 

RMS$_OK_WAT 

Record locked after wait 

00018069 

RMS$_CRE_STM 

File created in stream format 

00018071 

RMS$_OK_RULK 

See the VAX RMS Journaling Manual for details. 

00018198 

RMS$_BOF 

Beginning of file detected 

000181AO 

RMS$_RNL 

Record not locked 

000181A8 

RMS$_RTB 

nnn-byte record too large for user's buffer 

00018180 

RMS$_TMO 

Timeout period expired 

00018188 

RMS$_TNS 

Terminator not seen 

000181C0 

RMS$_BES 

Bad escape sequence 

000181C8 

RMS$_PES 

Partial escape sequence 

0001825A 

RMS$_ACT 

File activity precludes operation 

00018262 

RMS$_DEL 

RFA-accessed record deleted 

00018272 

RMS$_DNR 

Device not ready, not mounted, or unavailable 

0001827A 

RMS$_E0F 

End of the file detected 

00018282 

RMS$_FEX 

File already exists, not superseded 

0001828A 

RMS$_FLK 

File currently locked by another user 

00018292 

RMS$_FNF 

File not found 

0001829A 

RMS$_PRV 

Insufficient privilege or file protection violation 

000182A2 

RMS$_REX 

Record already exists 
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Table A-1 (Cent.) Completion Status Hexadecimal Values and Codes 

Hex Value 

Status Code 

Message Text 

000182A A 

RMS$_RLK 

Target record currently locked by another stream 

000182B2 

RMS$_RNF 

Record not found 

000182BA 

RMS$_WLK 

Device currently write-locked 

000182C2 

RMS$_EXP 

File expiration date not yet reached 

000182CA 

RMS$_NMF 

No more files found 

000182D2 

RMS$_SUP 

Network operation not supported; DAP code = nnnn 

000182DA 

RMS$_RSA 

Record stream currently active 

000182E2 

RMS$_CRC 

Network DAP level CRC check failed 

000182EA 

RMS$_WCC 

Invalid wild card context (WCC) value 

000182F2 

RMS$_IDR 

Invalid directory rename operation 

0001830A 

RMS$_NOVALPRS 

SSEARCH operation not preceded by valid SPARSE 

0001831A 

RMS$_RUH 

See the VAX RMS Journaling Manual for details. 

00018322 

RMS$_JND 

See the VAX RMS Journaling Manual for details. 

0001832A 

RMS$_BADPHASE 

See the VAX RMS Journaling Manual for details. 

00018332 

RMS$_TOWDR 

See the VAX RMS Journaling Manualfor details. 

0001833A 

RMS$_NEXDR 

See the VAX RMS Journaling Manual for details. 

00018342 

RMS$_INVDRMSG 

See the VAX RMS Journaling Manual for details. 

0001834A 

RMS$_RU_ACTIVE 

See the VAX RMS Journaling Manual for details. 

00018352 

RMS$_UNKRUFAC 

See the VAX RMS Journaling Manual for details. 

0001835A 

RMS$_LIMBO 

See the VAX RMS Journaling Manual for details. 

000183EC 

RMS$_DTFCDDREC 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

000183F4 

RMS$_AID 

Invalid area ID = n 

000183FC 

RMS$_ALN 

Alignment options error for area ID = n 

00018404 

RMS$_ALQ 

Invalid allocation quantity (negative, or 0 on $EXTEND) 

0001840C 

RMS$_ANI 

Not ANSI D format 

00018414 

RMS$_AOP 

Allocation options error for area ID = n 

0001841C 

RMS$_BKS 

Bucket size too large (FAB) 

00018424 

RMS$_BKZ 

Inconsistent bucket size for area ID = n 

0001842C 

RMS$_BLN 

Invalid block length for control block (RAB/FAB) 

00018434 

RMS$_BUG 

Internal RMS error condition detected 

0001843C 

RMS$_BUG_DD1 

Invalid default directory 

00018444 

RMS$_BUG_DAP 

Data Access Protocol error detected; DAP code = nnnn 

0001844C 

RMS$_BUG_RU_ 

ACTIVE 

See the VAX RMS Journaling Manual for details. 

00018454 

RMS$_BUG_RURECERR 

See the VAX RMS Journaling Manual for details. 

0001845C 

RMS$_BUG_FLUSH_ 

JNL-FAILED 

See the VAX RMS Journaling Manual for details. 

00018464 
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RMS$_BUG_RU_ 

ABORT_FAIL 

See the VAX RMS Journaling Manual for details. 






VMS RMS Completion Status Codes 


Table A-1 (Cont.) Completion Status Hexadecimal Values and Codes 


Hex Value 

Status Code 

Message Text 

0001848C 

RMS$_BUSY 

User structure (FAB/RAB) still in use 

00018494 

RMS$_CCR 

Cannot connect RAB 

0001849C 

RMS$_CHG 

Invalid key change in $UPDATE (CHG not set) 

000184A4 

RMS$_CHK 

Bucket format check failed for VBN =nnnn 

000184AC 

RMS$_COD 

Invalid or unsupported type field in XAB at nnnn 

000184B4 

RMS$_CUR 

No current record (operation not preceded by $GET/$FIND) 

000184BC 

RMS$_DAN 

Invalid data area number for key = n 

000184C4 

RMS$_DEV 

Error in device name or inappropriate device type for operation 

000184CC 

RMS$_DIR 

Error in directory name 

000184D4 

RMS$_DME 

Dynamic memory exhausted 

000184DC 

RMS$_DNA 

Invalid default file name string address 

000184E4 

RMS$_DTP 

Invalid key data type for key = n 

000184EC 

RMS$_DUP 

Duplicate key detected (DUP not set) 

000184F4 

RMS$_DVI 

Invalid device ID value in NAM block 

000184FC 

RMS$_ESA 

Invalid expanded string address 

00018504 

RMS$_ESS 

Expanded string area too small 

0001850C 

RMS$_FAB 

Invalid FAB or FAB not accessible 

00018514 

RMS$_FAC 

Record operation not permitted by specified file access (FAC) 

0001851C 

RMS$_FLG 

Invalid key definition flags for key = n 

00018524 

RMS$_FNA 

Invalid file name string address 

0001852C 

RMS$_FNM 

Error in file name 

00018534 

RMS$_FSZ 

Invalid fixed control header size 

0001853C 

RMS$_FOP 

Invalid file options 

00018544 

RMS$_FUL 

Device full (insufficient space for allocation) 

00018554 

RMS$_IAN 

Invalid index area number for key = n 

0001855C 

RMS$_IDX 

Index not initialized 

00018564 

RMS$_IFI 

Invalid internal file identifier (IFI) value 

0001856C 

RMS$_IMX 

Invalid duplicate XAB or nondense XAB at nnnn 

00018574 

RMS$_10P 

Operation invalid for file organization or device 

0001857C 

RMS$_IRC 

Illegal record encountered; VBN or record number = nnnn 

00018584 

RMS$_ISI 

Invalid Internal stream identifier (ISI) value 

0001858C 

RMS$_KBF 

Invalid key buffer 

00018594 

RMS$_KEY 

Invalid record number key or key value 

0001859C 

RMS$_KRF 

Invalid key-of-reference for $GET/$FIND 

000185A4 

RMS$_KSZ 

Invalid key size for $GET/$FIND 

000185AC 

RMS$_LAN 

Invalid lowest-level-index area number for key = n 

000185B4 

RMS$_RUNDOWN 

Operation Invalid during RMS rundown 

000185BC 

RMS$_LNE 

Logical name translation count exceeded 
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VMS RMS Completion Status Codes 

Table A-1 (Cent.) Completion Status Hexadecimal Values and Codes 

Hex Value 

Status Code 

Message Text 

000185C4 

RMS$_DTFCVT 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

000185CC 

RMS$_MRN 

Invalid maximum record number or record number exceeds 

MRN 

000185EC 

RMS$_DTFQUASYN 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

000185D4 

RMS$_MRS 

Invalid maximum record size 

000185DC 

RMS$_NAM 

Invalid NAM block or NAM block not accessible 

000185E4 

RMS$_NEF 

Not positioned to EOF on $PUT (sequential organization only) 

000185F4 

RMS$_NOD 

Error in node name 

000185FC 

RMS$_NPK 

No primary key defined for indexed file 

0001860C 

RMS$_ORG 

Invalid file organization value 

00018614 

RMS$_PBF 

Invalid prompt buffer 

0001861C 

RMS$_PLG 

Error detected in file's prolog (reconstruct file) 

00018624 

RMS$_POS 

Invalid key position (greater than MRS) for key = n 

0001862C 

RMS$_DTFQUAVAL 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

00018634 

RMS$_QUO 

Error in quoted string 

0001863C 

RMS$_RAB 

Invalid RAB or RAB not accessible 

00018644 

RMS$_RAC 

Invalid record access mode 

0001864C 

RMS$_RAT 

Invalid record attributes 

00018654 

RMS$_RBF 

Invalid record buffer 

0001865C 

RMS$_RFA 

Invalid record file address in RAB 

00018664 

RMS$_RFM 

Invalid record format 

0001866C 

RMS$_RHB 

Invalid record header buffer 

00018674 

RMS$_RLF 

Invalid related NAM block 

0001867C 

RMS$_R0P 

Invalid record options 

00018684 

RMS$_RRV 

Invalid RRV record encountered 

0001868C 

RMS$_RVU 

Error updating RRVs, some paths to data may be lost 

00018694 

RMS$_RSS 

Invalid resultant string size 

0001869C 

RMS$_RST 

Invalid resultant string address 

000186A4 

RMS$_RSZ 

Invalid record size 

000186AC 

RMS$_SEQ 

Primary key out of sequence (SEQ access) 

000186B4 

RMS$_SHR 

Invalid file-sharing (SHR) options 

000186BC 

RMS$_SIZ 

Invalid key size for key = n 

000186C4 

RMS$_SQO 

Operation not sequential (SQO set) 

000186CC 

RMS$_DTFSESEST 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

000186D4 

RMS$_SYN 

File specification syntax error 

000186DC 

RMS$_TRE 

Error In index tree 

000186E4 

RMS$_TYP 

Error in file type 

000186EC 
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VMS RMS Completion Status Codes 


Table A-1 (Cont.) Completion Status Hexadecimal Values and Codes 

Hex Value 

Status Code 

Message Text 

000186F4 

RMS$_USZ 

Invalid user buffer size 

000186FC 

RMS$_VER 

Error in version number 

00018704 

RMS$_XNF 

Required XAB not found 

0001870C 

RMS$_XAB 

Invalid XAB or XAB not accessible at nnnn 

00018714 

RMS$_ESL 

Invalid expanded string length 

0001871C 

RMS$_DTFSESTER 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

00018724 

RMS$_ENV 

Support for RMS service call or feature not present 

0001872C 

RMS$_PLV 

Unsupported prolog version 

00018734 

RMS$_MBC 

Invalid multiblock count 

0001873C 

RMS$_RSL 

Invalid resultant string length 

00018744 

RMS$_WLD 

Invalid wildcard operation 

0001874C 

RMS$_NET 

Network operation failed at remote node; DAP code = nnnn 

00018754 

RMS$_IBF 

Illegal bucket format in VBN = nnnn 

0001875C 

RMS$_REF 

Invalid key-of-reference = n 

00018764 

RMS$_IFL 

Index bucket fill size larger than bucket size for key = n 

0001876C 

RMS$_DFL 

Data bucket fill size larger than bucket size for key = n 

00018774 

RMS$_KNM 

Key name buffer not accessible for key 

0001877C 

RMS$_IBK 

LAN bucket size not equal to IAN bucket size for key = n 

00018784 

RMS$_KSI 

Index bucket cannot hold two keys for key-of-reference = n 

0001878C 

RMS$_LEX 

Invalid $EXTEND for area n containing an unused extent 

00018794 

RMS$_SEG 

Overlapping segments or segmented key must be string for 
key = n 

000187AC 

RMS$_UPI 

UPl not set when sharing and BIO or BRO set 

000187B4 

RMS$_ACS 

Error in access control string 

000187BC 

RMS$_STR 

User structure (FAB/RAB) became invalid during operation 

000187C4 

RMS$_FTM 

Network file transfer mode precludes operation (SQO set) 

000187CC 

RMS$_GBC 

Invalid global buffer count 

000187D4 

RMS$_DEADLOCK 

Deadlock detected 

000187DC 

RMS$_EXENQLM 

Exceeded enqueue quota 

000187E4 

RMS$_JOP 

See the VAX RMS Journaling Manual for details. 

000187F4 

RMS$_JNS 

See the VAX RMS Journaling Manual for details. 

000187FC 

RMS$_NRU 

See the VAX RMS Journaling Manual for details. 

00018804 

RMS$_IFF 

Invalid file attributes for requested file access 

0001880C 

RMS$_DTFTRATBL 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

00018814 

RMS$_DTFUNSTYP 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

0001881C 

RMS$_DTFVERMIS 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

00018824 

RMS$_DTFACC 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

00018824 

RMS$_DTFACC 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 
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Table A-1 (Cent.) Completion Status Hexadecimal Values and Codes 

Hex Value 

Status Code 

Message Text 

00018826 

RMS$_BOGUSCOL 

Invalid or inaccessible collating table 

00018834 

RMS$_ERRREADCOL 

Error encountered while trying to read collating table 

00018836 

RMS$_ERRWRITECOL 

Error encountered while trying to write collating table 

00018854 

RMS$_DTFCRE 

See 

the DECnet/SNA VMS Data Transfer Facility User's Guide. 

00018864 

RMS$_NOTSAMEJNL 

See 

the VAX RMS Journaling Manual for details. 

0001885C 

RMS$_DELJNS 

See 

the VAX RMS Journaling Manual for details. 

0001C002 

RMS$_ACC 

ACP file access failed 

0001 COOA 

RMS$_CRE 

ACP file create failed 

0001C012 

RMS$_DAC 

ACP file deaccess failed during $CLOSE 

0001C01A 

RMS$_ENT 

ACP enter function failed 

0001C022 

RMS$_EXT 

ACP file extend failed 

0001C02A 

RMS$_FND 

ACP file or directory lookup failed 

0001C032 

RMS$_MKD 

ACP could not mark file for deletion 

0001C03A 

RMS$_DPE 

Device positioning error 

0001C042 

RMS$_SPL 

Spool or submit of command file failed on $CLOSE 

0001C04A 

RMS$_DNF 

Directory not found 

0001C052 

RMS$_RUF 

See 

! the VAX RMS Journaling Manual for details. 

0001C05A 

RMS$_WRTJNL_AIJ 

See 

f the VAX RMS Journaling Manual for details. 

0001C062 

RMS$_WRTJNL_BIJ 

See 

s the VAX RMS Journaling Manual for details. 

0001C072 

RMS$_WRTJNL_RUJ 

See 

! the VAX RMS Journaling Manual for details. 

0001C07A 

RMS$_RRF 

See 

! the VAX RMS Journaling Manual for details. 

0001C0CC 

RMS$_ATR 

File 

attributes read error 

0001C0D4 

RMS$_ATW 

File 

attributes write error 

0001C0DC 

RMS$_CCF 

Cannot close file 

0001C0E4 

RMS$_CDA 

Cannot deliver AST 

0001C0EC 

RMS$_CHN 

Assign channel system service request failed 

0001C0F4 

RMS$_RER 

File 

read error 

0001C0FC 

RMS$_RMV 

ACP remove function failed 

0001C104 

RMS$_RPL 

Error detected while reading prolog 

0001C10C 

RMS$_SYS 

QIC 

1 system service request failed 

0001C114 

RMS$_WER 

File 

write error 

0001C11C 

RMS$_WPL 

Error detected while writing prolog 

0001C124 

RMS$_IFA 

Illegal file attributes detected (file header corrupted) 

0001C12C 

RMS$_WBE 

Error on write behind 

0001C134 

RMS$_ENQ 

ENQ system service request failed 

0001C13C 

RMS$_NETFAIL 

Network operation failed at remote node 
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Table A-1 (Cont.) Completion Status Hexadecimal Values and Codes 

Hex Value 

Status Code 

Message Text 

0001C144 

0001C14C 

0001 Cl 54 

0001 Cl5C 

0001C164 

0001C16C 

0001 Cl 74 

0001C17C 

0001C18C 

0001 Cl 94 

RMS$_SUPPORT 

RMS$_CRMP 

RMS$_DTFCFGFIL 

RMS$_REENT 

RMS$_ACC_RUJ 

RMS$_TMR 

RMS$_ACC_AIJ 

RMS$_ACC_BIJ 

RMS$_DTFDEFFIL 

RMS$_DTFREGFIL 

Network operation not supported 

CRMPSC system service failed to map global buffers 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 
File could not be renamed and recovery failed; file has been lost 
See the VAX RMS Journaling Manual for details. 

SETIMR system service request failed 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 
See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

Table A-2 

Descriptions of VMS RMS Completion Status Codes 

Status Code 

Description 



RMS$_ACC File access error; the STV field contains an ACP error code. Take corrective 

action appropriate to the STV status code. 


RMS$_ACS 

RMS$_ACC_AIJ 

RMS$_ACC_BIJ 

RMS$_ACC_RUJ 

RMS$_ACT 

RMS$_AID 


Error in access control string of the node name. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling ManuaMor details. 

File activity precludes operation; operation attempted during other file I/O. 
Modify the source program to detect and respond to this condition. 

Bad area identification number field in allocation XAB; the STV field contains the 
area ID. 


RMS$_ALN 


Invalid alignment boundary type in allocation XAB; the STV field contains the 
area ID. 


RMS$_ALQ 

RMS$_ANI 

RMS$_AOP 

RMS$_ATR 

RMS$_ATW 

RMS$_BADPHASE 

RMS$_BES 

RMS$_BKS 


Incorrect allocation quantity; the value exceeds the maximum allowed (Create 
service) or exceeds the maximum allowed or is equal to zero (Extend service). 

Records In a magnetic tape file are not ANSI D format. 

Invalid allocation option in allocation XAB; the STV field contains the area ID. 

Read error on file header; the STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, If possible. 

Write error on file header; the STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 

See the VAX RMS Journaling Manual for details. 

Bad escape sequence (terminals only, warning). Modify the source program to 
detect and recognize this condition or reenter the Input specifying the correct 
escape sequence. 

Invalid bucket size in FAB or inconsistent record length. The bucket size 
specified in the FAB is larger than 63. If the bucket size is specified as zero, the 
maximum record size is too large. 
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Table A-2 (Cont.) 
Status Code 
RMS$_BKZ 
RMS$_BLN 

RMS$_BOF 


RMS$_BOGUSCOL 


RMS$_BUG 

RMS$_BUG_DAP 

RMS$_BUG_DDI 

RMS$_BUG_FLUSH_ 

JNL_FAILED 

RMS$_BUG_ 

RUCRECERR 

RMS$_BUG_RU_ 

ABORT_FAIL 

RMS$_BUG_RU_ 

ACTIVE 

RMS$_BUSY 


RMS$_CCF 

RMS$_CCR 


Descriptions of VMS RMS Completion Status Codes 
Description 

Invalid bucket size in the allocation XAB; the STV field contains the area ID. 

Invalid value in block length field; this completion code is not available in the 
FAB$L_STS/FAB$L_STV or RAB$L_STS/RAB$L_STV fields. 

Beginning of file detected (warning); you invoked the Rewind service or Space 
service at the beginning of the file. The STV field contains the number of blocks 
spaced. You may need to modify the source program to detect and respond to 
this condition. 

Either the collating sequence is missing, is inaccessible to RMS, or Is in a format 
that RMS cannot interpret. This situation is typically created by an application 
program error. Verify that a valid NCS sequence is available to RMS. 

Internal VMS RMS error detected. Submit an SPR. 

Data Access Protocol error. Submit an SPR. 

Invalid default directory. Submit an SPR. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

FAB or RAB cannot be used because either a prior operation needs to complete 
before VMS RMS can use the FAB or RAB for the requested operation, or the 
user illegally called VMS RMS from executive mode at AST level or from kernel 
mode and interrupted another VMS RMS operation. Use multiple I/O streams or 
use the Wait service as necessary. This completion code Is not available in the 
FAB$L_STS/FAB$L_STV or RAB$L_STS/RAB$L_STV fields. 

For the $CLOSE service, an output file could not be closed successfully; user 
buffer Identifies the file by its device ID and file ID. 

Cannot connect RAB; process has specified either a nonexistent or inaccessible 
RAB. This usually results from one of the following actions: 


• The program tried to do block I/O (setting RAB$V_BIO in RAB$L_ROP) with 
multistreaming (setting FAB$V_MSE bit In FAB$B_SHR). 


• The program tried to connect to multiple RABs to a FAB without first setting 
the FAB$V_MSE bit in the FAB$B_SHR field. 


• The program tried to use multistreaming with file access across DECnet. 


RMS$_CDA 


RMS$_CHG 


Cannot deliver AST; the STV field contains the STS value of the operation. The 
AST limit quota for the process has probably been exhausted. You need to 
Increase the quota or decrease the level of AST activity. Take corrective action 
for the actual operation based on the STV value. 

The process tried to change a key value in a file that does not have the key 
change option. 
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Table A—2 (Cent.) Descriptions of VMS RMS Completion Status Codes 
Status Code Description 

RMS$_CHK Index file bucket check byte mismatch; the bucket has been corrupted. The STV 

field contains the VBN of the bucket. This error can be caused by any of the 
following conditions: 

• The combination of a disk backed up using standalone BACKUP and files 
with the /NOBACKUP qualifier 

• Inadvertent modification of the file using block I/O or non-VMS RMS 
programs 

• Hardware, VMS RMS, or other system software errors 


RMS$_CHN 

RMS$_COD 

RMS$_CONTROLC 

RMS$_CONTROLO 

RMS$_CONTROLY 

RMS$_CRC 

RMS$_CRE 

RMS$_CREATED 

RMS$_CRE_STM 

RMS$_CRMP 


RMS$_CUR 

RMS$_DAC 

RMS$_DAN 

RMS$_DEADLOCK 


Try to recreate the rest of the file. If the problem recurs and appears to be 
caused by VMS RMS or system software, submit an SPR. 

Channel assignment failure; the STV field contains a system error code. Take 
corrective action appropriate to the STV status code, if possible. 

Invalid type code in XAB; the STV field contains the XAB address. 

Operation completed under CTRL/C; terminal I/O may have been truncated 
(success). 

Operation completed under CTRL/0; terminal output may have been truncated 
(success). 

Operation completed under CTRL/Y; terminal I/O may have been truncated 
(success). 

Network DAP level CRC failed on Close. The network link may be experiencing 
hardware errors. Retry the operation. 

ACP file creation failed. The STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code. 

File created with the FAB$V_CIF (create-if) option because the file was not 
found. If the file is found, it is opened (not created) and RMS$_NORMAL is 
returned (success). 

File created in stream format (success). 

For the Connect service, the requested number of global buffers Is unobtainable; 
no global sections or an insufficient number of global pages or global page file 
entries were available to grant the requested number of global buffers. Reduce 
the number of global buffers requested in the FAB$W_GBC field and retry 
the Connect service, or wait until an orderly shutdown of the system can be 
arranged and Increase the appropriate system generation parameters, then retry 
the operation. 

No current record; operation not immediately preceded by a successful Get or 
Find service. 

ACP file deaccess failed during Close. The file was deaccessed. The STV field 
contains an ACP error code. Take corrective action appropriate to the STV 
status code. 

Invalid data area number in key definition XAB; the STV field contains the key 
number. 

The VMS lock manager detected a deadlock. Modify the source program. If 
necessary. 
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Table A-2 (Cent.) 
Status Code 
RMS$_DEL 

RMS$_DELJNS 

RMS$_DEV 

RMS$_DFL 

RMS$_DIR 


RMS$_DME 


RMS$_DNA 

RMS$_DNF 


RMS$_DNR 


RMS$_DPE 


RMS$_DTFACC 

RMS$_DTFCDDREC 

RMS$_DTFCFGFIL 

RMS$_DTFCRE 

RMS$_DTFCVT 

RMS$_DTFDEFFIL 

RMS$_DTFQUASYN 

RMS$_DTFQUAVAL 

RMS$_DTFREGFIL 

RMS$_DTFSESEST 

RMS$_DTFSESTER 

RMS$_DTFTRATBL 

RMS$_DTFUNSTYP 


Descriptions of VMS RMS Completion Status Codes 
Description 

RFA-accessed record deleted; the program attempted to access a previously 
deleted record. Modify the source program, if necessary. 

See the VAX RMS Journaling Manual for details. 

Bad device or inappropriate device type for operation. 

Data bucket fill size larger than bucket size specified in the key definition XAB; 
the STV field contains the key number. 

Error in directory name; the directory name specified incorrectly. For example, a 
directory or subdirectory name exceeded 39 characters in length, or the use of 
a logical name resulted in more than one directory name in the file specification. 
Verify the syntax of either the directory name in the file specification or the 
logical name, if applicable. 

Dynamic memory exhausted. Occurs only if the related I/O segment in the 
control region Is full and the file Is either a direct access process-permanent file 
or the user has disallowed the use of the program region for I/O buffers to RMS. 

Invalid default file specification string address. 

Directory.not found; specified directory name does not exist on the specified 
device. Verify that the device and directory are specified correctly. Create 
the directory on that device or use a different directory. When performing an 
Open service, consider using a search list logical name if the same file exists in 
multiple device/directory locations. The STV field contains a system error code. 
Take corrective action appropriate to the STV status code. 

Device not ready, not mounted, or unavailable. Make sure that the volume is 
physically loaded, that the device Is ready, and that the DCL command MOUNT 
has been completed successfully. Check that the correct controller is set on the 
drive. Retry the operation. 

Device positioning error; magnetic tape improperly positioned. Examine the 
RAB$L_STV field for secondary status information; take corrective action 
appropriate to this Information. Retry the operation. If this error persists. It may 
indicate a system software or hardware failure. Contact your system operator 
or manager. 


See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 
See the DECnet/SNA VMS Data 


Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 
Transfer Facility 


User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
User's Guide. 
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Table A—2 (Cent.) Descriptions of VMS RMS Completion Status Codes 


Status Code 

Description 

RMS$_DTFVERMIS 

RMS$_DTP 

RMS$_DUP 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 

Invalid data type in key definition XAB; the STV field contains the key number. 

Duplicate key detected; key definition XAB key option flag not set to allow 
duplicate key values. 

RMS$_DVI 

RMS$_ENQ 

Invalid device Identification in the NAM block. 

Lock manager system service failed; the STV field contains a $ENQ system 
service error code. Take corrective action appropriate to the STV status code, 
if possible. 

RMS$_ENT 

ACP enter function failed. The STV field contains an AGP error code. Take 
corrective action appropriate to the STV status code, if possible. 

RMS$_ENV 

Environment error; support for the VMS RMS service or selected option is not 
present in system. 

RMS$_EOF 

For Find or Get services, end of the file detected; the program attempted to read 
beyond the last record in the file. If necessary, modify the source program to 
detect and respond to the condition. 

For a Read (block I/O) service, end of the file detected. Checking for the logical 
end of the file Is performed only for sequential file organization. If an RMS$_EOF 
error occurs. It implies that the first virtual block number specified is at or past 
the end of the file. If the RMS$_EOF error occurs during a transfer, the record 
size field is set to the number of bytes before the logical end of the file. For 
relative or indexed file organization, this status code indicates an attempt to read 
past the end of the currently allocated space. 

For a Write service (block I/O), end of the file detected for a sequential file; 
implies that the file could not be extended. Determine whether sufficient disk 
space is available on the disk device in use (use the DCL command SHOW 
DEVICE). If you do not have enough space, purge or delete files that are no 
longer needed; then retry the operation. 

RMS$_ERRREADCOL 

An I/O error occurred when the program tried to read the file's collating 
sequence. This is typically due to a hardware problem; otherwise, submit 
an SPR. 

RMS$_ERRWRITECOL 

An I/O error occurred when the program tried to write the sequence to the file. 
This is usually due to a hardware problem; otherwise, submit an SPR. 

RMS$_ESA 

RMS$_ESL 

RMS$_ESS 

RMS$_EXENQLM 

Invalid expanded string area address in NAM block. 

Invalid expanded string length In NAM block. 

Expanded string area too short. 

Exceeded process enqueue limit. Reduce the number of locks held at one time 
and retry, or have the system manager increase this limit for your process. Log 
out and log in, and then retry the operation. 

RMS$_EXP 

File expiration date not yet reached; tried to overwrite magnetic tape files. If the 
file can be overwritten, remount the volume using the /OVERRIDE=EXPIRATION 
qualifier. (You must be the volume owner or have VOLPRO privilege to overwrite 
a volume.) Otherwise, use a different volume. 

RMS$_EXT 

ACP file extend failed. The STV Held contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 
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Table A-2 (Cent.) 

Descriptions of VMS RMS Completion Status Codes 

Status Code 

Description 

RMS$_FAB 

Invalid FAB; block identifier field incorrect. This completion code is not available 
in the FAB$L_STS/FAB$L_STV fields. 

RMS$_FAC 

Operation not allowed by the value set in the FAB$B_FAC field. For the Extend 
service, verify that the FAB$B_FAC field specifies put or update access for the 
file to be extended. Modify the source program if necessary. 

RMS$_FEX 

File already exists, not superseded; the program attempted to create or rename 
a file with the same file specification as an existing file. Choose a different file 
specification; delete the existing file (if a new file is to be created). For the 
Create service, consider using the FAB$L_FOP field FAB$V_SUP option to 
request that an existing file be superseded. 

RMS$_FILEPURGED 

This informational message indicates that the newly created file version 
exceeded the maximum number of versions allowed for the file; therefore, 
the oldest version is deleted. 

RMS$_FLG 

Invalid combination of values in key XAB$B_FLG field; the STV field contains 
the key number. (Example: XAB$V_CHG or XAB$V_NUL for primary key.) 

RMS$_FLK 

File currently locked by another user; the program attempted to create or open 
a file that is currently being accessed by another user, and the file was not 
accessed for sharing. Walt until the other user deaccesses the file and retry the 
operation. 

RMS$_FNA 

RMS$_FND 

Invalid file specification string address in FAB. 

ACP file or directory lookup failed; error occurred during a directory search. The 
STV field contains an ACP error code. Take corrective action appropriate to the 
STV status code, If possible. 

RMS$_FNF 

File not found. Check the file specification and verify that the device, directory, 
file name, and file type are correct. If a logical name was specified, verify that 
the current equivalence name assigned to the logical name is correct. Verify that 
the correct volume is mounted and that the file was not inadvertently deleted. 

RMS$_FNM 

RMS$_FOP 

RMS$_FSZ 

RMS$_FTM 

RMS$_FUL 

RMS$_GBC 

RMS$_IAL 

Syntax error in file name. 

Invalid file-processing options. 

Invalid fixed control area size in FAB (equal to 1 for print files). 

Network DAP file transfer mode does not permit operation. 

Device full; cannot create or extend file. 

Invalid global buffer count. 

Invalid argument list. Applies to the SYS$RMSRUNDWN, SYS$SETDFPROT, 
and SYS$SETDDIR services. See the VMS System Services Reference Manual. 

RMS$_IAN 

Invalid index area number In key definition XAB; the STV field contains the key 
number. 

RMS$_IBF 

RMS$_IBK 

Invalid bucket format; STV contains bucket VBN. Submit an SPR. 

Bucket size of lowest level of index area number (XAB$B_LAN) not equal to that 
of specified index area number (XAB$B_IAN field) in key definition XAB; the 
STV field contains the key number. 

RMS$_IDR 

Invalid directory rename operation; attempted to rename a directory file Into 
a directory tree that contained the directory file. The directory would then be 
inaccessible. 
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Table A-2 (Cont.) 

Descriptions of VMS RMS Completion Status Codes 

Status Code 

Description 

RMS$_IDX 

RMS$_IFA 

Index not initialized; internal VMS RMS error. Submit an SPR. 

Invalid file attributes; file header corrupted. Check the STV field for additional 
information. Take corrective action appropriate to the STV status code, if 
present. 

RMS$_IFF 

Invalid file attributes for requested access. Usually, this occurs when attempting 
to open an ANSI magnetic tape file for write access and the file has a nonzero 
value for Its buffer offset value. VMS RMS does not allow the creation of a 
magnetic tape file with a nonzero buffer offset. You can, however, access such 
a file for read and write operations if you specify block I/O. 

RMS$_IFI 

Invalid internal file identifier in FAB; file already closed or not open (Close or 
Connect services), file already open or not closed (Create service), file not open 
(Display and Extend services), or file already open (other services). 

RMS$_IFL 

Index bucket fill size larger than bucket size specified in key definition XAB; the 
STV field contains the key number. 

RMS$_IMX 

More than one XAB of the same type or nondense XAB is present for the file; 
the STV field contains the XAB address. 

RMS$_INVDRMSG 

RMS$_10P 

See the VAX RMS Journaling Manual for details. 

Invalid operation attempted; operation is one of following: (1) block I/O 
when record I/O access, (2) record I/O when block I/O access, (3) rewind of 
process-permanent file, (4) inappropriate device type or file organization. 

RMS$_IRC 

Invalid record encountered in file or invalid byte count field or control byte field 
contained in that record; the STV field contains the virtual block number for 
sequential and indexed files or the relative record number for relative files of the 
corrupted record. This error can be caused by the following conditions: 

• The combination of a disk backed up using standalone BACKUP and files 
with the /NOBACKUP qualifier 

• Inadvertent modification of files by block I/O or non-VMS RMS programs 

• Hardware errors, VMS RMS errors, or other system software errors. 

RMS$_ISI 

For sequential and indexed files, try to recreate the rest of the file. For relative 

files, reinsert the bad record with the Put service using the RAB$I_ROP field 

RAB$V_UIF option. If this does not solve the problem, submit an SPR. 

Invalid internal stream Identifier in RAB; record stream already connected 
(Connect service) or was not connected (other services). 

RMS$_JND 

RMS$_JNS 

RMS$_JOP 

RMS$_KBF 

RMS$_KEY 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

Invalid key buffer address. 

Invalid record key for random operation to a relative file or invalid packed 
decimal key for an Indexed file. 

RMS$_KFF 

RMS$_KNM 

Known file found; this code is reserved for DIGITAL usage only. 

Invalid key name buffer address In key definition XAB; the STV field contains 
the key number. 

RMS$_KRF 

Invalid key of reference in RAB$B_KRF field. 
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Table A~2 (Cont.) Descriptions of VMS RMS Completion Status Codes 


Status Code 
RMS$_KSI 

RMS$_KSZ 

RMS$_LAN 

RMS$_LEX 

RMS$_LNE 


RMS$_MBC 

RMS$_MKD 

RMS$_MRN 

RMS$_MRS 

RMS$_NAM 

RMS$_NEF 

RMS$_NET 

RMS$_NETFAIL 

RMS$_NMF 


RMS$_NOD 

RMS$_NORMAL 

RMS$_NOVALPRS 

RMS$_NPK 

RMS$_OK_ALK 

RMS$_OK_DEL 

RMS$_OK_DUP 


Description 

The size of the index buckets specified for the key must be large enough to hold 
at least two key values: the STV value contains the key of reference. 

Key size not equal to 4 (relative file) or key size too large (indexed file). 

Invalid index lowest-level-bucket area number in key definition XAB; the STV 
field contains the key number. 

Attempted to extend area containing an unused extent. 

Logical name error; an error was detected in file name processing. Usually this 
is caused by exceeding the maximum logical name translation count, typically 
when the equivalence string for a logical name Is identical to the name itself. 
This error can also Indicate a fatal error in logical name translation, or invalid 
syntax for a process-permanent file equivalence string. 

Invalid multiblock count. Must not be greater than 127. 

ACP could not mark file for deletion. The STV field contains an ACP error code. 
Take corrective action appropriate to the STV status code. If possible. 

Invalid value for maximum record number (negative) or relative key greater than 
maximum record number. 

Invalid value for maximum record size. 

Invalid or inaccessible NAM block. 

Attempted to use the Put service to a sequential file not positioned to the end 
of the file. 

Network operation failed at remote node; the STV field contains a DAP code. 
Take corrective action appropriate to the STV status code, if possible. 

Network operation failed at remote node; the STV field contains an FAL status 
code. Take corrective action appropriate to the STV status code. If possible. 

No more files found; the directory or volume set does not contain any more files 
that meet the file specification (wildcard operation). This Is the normal status to 
indicate the end of a wildcard search operation. Modify the source program, if 
necessary, to detect and respond to this condition. 

Node name error. 

Operation successful (synonym for RMS$_SUC, success). 

Search service not preceded by a Parse service. Correct the source program to 
invoke the Parse service before Invoking the Search service. 

No primary key defined in key definition XAB when creating an Indexed file. 

Record is already locked; the program attempted to lock a previously locked 
record. No action is usually required, although this can depend on application 
requirements (success). 

Deleted record successfully accessed; a previously deleted record was read 
successfully. No action is usually required, although this can depend on 
application requirements (success). 

Record Inserted had duplicate key; the record was inserted successfully and had 
one or more key values that duplicated the values of other records (success). 
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Table A-2 (Cent.) 
Status Code 
RMS$_OK_IDX 


RMS$_OK_LIM 


RMS$_LIMBO 

RMS$_NEXDR 

RMS$_NOTSAMEJNL 

RMS$_NRU 

RMS$_OK_NOP 


RMS$_OK_RLK 

RMS$_OK_RNF 

RMS$_OK_RRL 

RMS$_OK_RULK 

RMS$_OK_WAT 

RMS$_ORG 

RMS$_PBF 

RMS$_PENDING 

RMS$_PES 


RMS$_PLG 

RMS$_PLV 

RMS$_POS 

RMS$_PRV 


RMS$_QUO 


Descriptions of VMS RMS Completion Status Codes 
Description 

Index update error occurred; the record was inserted successfully but an error 
occurred on index update, which could cause slow access to that record 

using that key path. Examine the value of the VMS RMS error in the RAB$I_ 

STV field. Take corrective action appropriate to the STV status code. File 
reorganization is recommended (success). 

Retrieved record exceeds specified key value; the retrieved record exceeds the 
specified key value when the RAB$L_ROP RAB$V_LIM option was specified. It 
was read successfully. No action is usually required, although this can depend 
on application requirements (success). 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

XAB not filled in for block I/O; operation executed successfully when block 
I/O access was specified. One or more XABALL or XABKEY blocks were not 
filled. No action Is usually required, although this can depend on application 
requirements (success). 

Record locked but read anyway; the retrieved record was locked but was read 
successfully. No action is required (success). 

Nonexistent record successfully accessed; a nonexistent record was read 
successfully. No action is required (success). 

Record locked against read, but read anyway; a record locked against reading 
was read successfully. No action is required (success). 

See the VAX RMS Journaling Manual for details. 

Record locked after wait; the retrieved record was locked but has been read 
successfully after a wait period. No action is required (success). 

Unknown file organization. 

Invalid prompt buffer address. 

An asynchronous operation was initiated but is not yet completed; no action Is 
required (success). 

Partial escape sequence (terminals only, warning); the user buffer was filled 
before a complete escape sequence was entered. The remainder of the escape 
sequence is returned with the next input operation. Increase the size of the 
user buffer to allow escape sequences or modify the program, if necessary, to 
recognize and respond to this condition. 

Error in file prolog; file is corrupted. 

Prolog version unsupported. 

Invalid key position (greater than MRS) in key definition XAB; the STV field 
contains the key number. 

Insufficient privilege or file protection violation; the current process is denied 
access because of the file protection. Check the access rights associated 
with the file and change them if needed. If you are not the file owner or have 
insufficient privilege, request that the file owner change the protection. 

Error in quoted string. 
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Table A-2 (Cont.) Descriptions of VMS RMS Completion Status Codes 

Status Code 

Description 

RMS$_RAB 

Not a valid RAB; block identifier field incorrect. This completion code is not 
available in the RAB$L_STS/RAB$L_STV fields. 

RMS$_RAC 

Invalid value in record access mode field of RAB. 

RMS$_RAT 

Record attributes invalid in FAB. 

RMS$_RBF 

Invalid record address. 

RMS$_REENT 

An attempt to use the ACP enter function for new file specification failed after 
the old file specification was removed, making It impossible to reenter the file 
specification. Examine the STV field for additional information. The file could 
not be renamed and recovery failed; the file has been lost. 

RMS$_REF 

Invalid key of reference in XAB; key of reference was greater than number In file 
or equal to 255. 

RMS$_RER 

File read error; the STV field contains a system error code. Take corrective 
action appropriate to the STV status code, if possible. 

RMS$_REX 

Record already exists; while inserting a record into a relative file using random 
access mode, the specified record number is the same as an existing record; the 
new record was not written over the existing record. Note the condition. Modify 
the source program, if necessary, to detect and respond to this condition. You 
may want to specify the RAB$I_ROP field RAB$V_UIF option. 

RMS$_RFA 

Invalid record file address contained in RAB. 

RMS$_RFM 

Invalid record format. 

RMS$_RHB 

Invalid or Inaccessible record header buffer. 

RMS$_RLF 

Invalid or inaccessible related file block, or user has exceeded the limit of 255 
related file name blocks, or related file name blocks are linked circularly. 

RMS$_RLK 

Target record currently locked by another stream; the requested record cannot 
be accessed. Modify the source program, if necessary, to detect and respond 
to this condition. 

RMS$_RMV 

ACP remove operation failed. The STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 

RMS$_RNF 

Record not found; the requested record in an Indexed or relative file either was 
never written or was deleted. Modify the source program. If necessary, to 
detect and respond to this condition. 

RMS$_RNL 

Record not locked (warning); no records were locked for this record stream 
when the operation was invoked. If necessary, modify the source program. 

RMS$_ROP 

Invalid record option^ 

RMS$_RPL 

Error while reading Prolog; the STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 

RMS$_RRF 

See the VAX RMS Journaling Manual for details. 

RMS$_RRV 

Invalid RRV record ehcountered in indexed file; file may be corrupted. 

RMS$_RSA 

Record stream currently active (asynchronous operations); operation attempted 
while an I/O request was outstanding for this record stream. 

RMS$_RSL 

Resultant string length field of NAM block invalid. 

RMS$_RSS 

Resultant string area size is too small. 

RMS$_RST 
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Table A-2 (Cont.) 

Descriptions of VMS RMS Completion Status Codes 

Status Code 

Description 

RMS$_RSZ 

RMS$_RTB 

Invalid record size. 

Record too large for user's buffer (warning); the record just returned was too 

large for the user buffer provided. The RAB$I_STV field contains the size of 

the record; the returned record is truncated to the size of the user buffer. Modify 
the source program by increasing the size of the user buffer. You can determine 
the size of the largest record in a file using the DCL command ANALYZE/RMS_ 
FILE or by examining the contents of the XABFHC field XAB$W_LRL after 
opening the file with the XABFHC chained to the FAB. 

RMS$_RUF 

RMS$_RUH 

RMS$_RU_ACTIVE 

RMS$_RUH 

RMS$_RVU 

See the WAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

Error while updating RRVs; some paths to data may be lost. File reorganization 
is strongly recommended. 

RMS$_RUNDOWN 

RMS$_SEG 

Operation invalid during RMS rundown. 

Segmented key for key data type other than string. The STV field contains the 
key of reference. 

RMS$_SEQ 

Primary key of record to be written is not equal to or greater than key of 
previous record and RAB$B_RAC field is set to RAB$V_SEQ. 

RMS$_SHR 

Invalid value in the file-sharing field of FAB. This condition can be caused by 
attempting to access a sequential file that cannot be shared. (Only relative files, 
indexed files, and sequential files with 512-byte fixed-length records can be 
shared.) 

RMS$_SIZ 

Invalid key size specified In key definition XAB XAB$B_SIZO through XAB$B_ 
SIZ7 field; specified size exceeds maximum record size, not equal to defined 
length on binary and integer key data types, greater than 16 for packed decimal 
key data type, or equal to 0 for string or packed decimal. The STV field contains 
the key of reference. 

RMS$_SPL 

Spool or submit command file option to a Close service failed; the STV field 
contains a system error code. Take corrective action appropriate to the STV 
status code. 

RMS$_SQO 

Operation not sequential; file was opened with FAB$I_FOP field FAB$V_SQO 

option, random access is not permitted. 

RMS$_STR 

User structure (FAB/RAB) became Invalid during the execution of a file or record 

operation. This completion code is not available In the FAB$I_STS/FAB$I_ 

STV or RAB$L_STS/RAB$L_STV fields. 

RMS$_SUC 

RMS$_SUP 

Operation successful (synonym for RMS$_NORMAL). 

Network operation not supported; the STV field contains a DAP code. Take 
corrective action appropriate to the STV status code. If possible. 

RMS$_SUPERSEDE 

Created file supersedes existing version of same file; no action is required 
(success). 

RMS$_SUPPORT 

Network operation not supported; the STV field contains a FAL/DAP status 
code. Take corrective action appropriate to the STV status code, if possible. 

RMS$_SYN 

Syntax error in file specification. 
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Table A-2 (Cont.) Descriptions of VMS RMS Completion Status Codes 

Status Code 

Description 

RMS$_SYS 

Error in system QIO directive; the STV field contains the directive or QIO status 
code. Take corrective action appropriate to the STV status code, if possible. 

RMS$_TMO 

Timeout period expired (terminal input, locked record, or mailbox devices, 
warning); the Find, Get, or Read service did not complete. For terminal and 
mailbox devices, the characters (if any) received before the timeout period 


expired are discarded. For disk record operations, the requested record was 
locked for the entire timeout period and was not read. Modify the source 
program, if necessary, to detect this condition and retry the requested service. 

RMS$_TMR 

SETIMR system service request failed. 

RMS$_TNS 

Terminator not seen (terminals only; warning); the terminal Get service 
terminated when the user buffer was filled to capacity, before a terminator 
sequence was encountered. Subsequent Get services can retrieve additional 
characters from that input line, including the terminator character sequence, 
which Is not in the current user buffer. Modify the source program to detect 
and respond to this situation or provide a user buffer large enough to contain an 
entire input line Including the terminator character sequence. 

RMS$_TOWDR 

See the VAX RMS Journaling Manual for details. 

RMS$_TRE 

Index tree error; file Is corrupted. 

RMS$_TYP 

Error in file type. 

RMS$_UBF 

Invalid user record buffer address. 

RMS$_UNKRUFAC 

See the VAX RMS Journaling Manual for details. 

RMS$_UPI 

The FAB$B_SHR field FAB$V_UPI option not set when file sharing FAB$I_FOP 

field FAB$V_BIO or FAB$V_BRO option was set. 

RMS$_USZ 

Invalid user record area size. 

RMS$_VER 

Error in version number. 

RMS$_WBE 

Error writing behind; the STV field contains a system error code. Take 
corrective action appropriate to the STV status code. If possible. 

RMS$_WCC 

Invalid wildcard context value. Verify that the NAM block has not been 
inadvertently modified between VMS RMS service calls. 

RMS$_WER 

File write error; the STV field contains a system error code. Take corrective 
action appropriate tO the STV status code. If possible. 

RMS$_WLD 

Invalid wildcard operation. 

RMS$_WLK 

Device currently wri^e-locked when write access was attempted. Verify the 
status of the devicej reset the write-lock switch, if necessary. Notify the system 
operator if the error cannot be corrected. 

RMS$_WPL 

Error while writing prolog; the STV field contains an AGP or system error code. 
Take corrective action appropriate to the STV status code, if possible. 

RMS$_WRTJNL_AIJ 

See the VAX RMS Journaling Manual for details. 

RMS$_WRTJNL_BIJ 

See the VAX RMS Journaling Manual for details. 

RMS$_WRTJNL_RUJ 

See the VAX RMS Journaling Manual for details. 

RMS$_XAB 

Not a valid XAB, not readable or writable, invalid code or length; the STV field 
contains the XAB address. 

RMS$_XNF 
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Could not locate XAB needed for this operation. Modify the source program 
to include the XAB and specify the address of the XAB In the FAB$L_XAB or 
RAB$L_XAB field. 





RMS Control Block Macros 


This appendix lists the format of each VMS RMS control block macro and 
includes special syntax notes that differ from the rules provided in Part I. 
Note that in this appendix the use of the term "macro" refers to a VAX 
MACRO macro. 
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VMS RMS Control Block Macros 

$FAB 


$FAB 


The $FAB macro allocates storage for a FAB and initializes certain FAB 
fields with defaults and user-specified values. No value is returned for this 
assembly-time operation. 


FORMAT 


$FAB ALQ = allocation-quantity, 


BKS = bucket-size, 

BLS = block-size, 

CHAN—MODE = channel-access-mode 
CTX = user-context-value, 

DEQ = extension-quantity, 

DNA = default-filespec-address, 

DNM = <filespec> , 

DNS = default-filespec-string-size, 

FAC = <BIO BRO DEL GET PUT TRN UPD> , 
FNA = filespec-string-address, 

FNM = <filespec> , 

FNS = filespec-string-size, 

<CBT CIF CTG DFW DL T 
MXV NAM NEF NFS OFP 
FOP = POS RCK RWC RWO SCF 
SPL SQO SUP TEF TMD 
TMPUFOWCK>, 

FSZ= header-size, 

GBC = global-buffer-count, 

LNM mode = 


access-mode. 


MRN = maximum-record-number, 
MRS = maximum-record-size, 
NAM = nam-address. 


ORG = 



RAT=l <bLKFTN> 
i PRN 
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ARGUMENTS 


VMS RMS Control Block Macros 

$FAB 


FIX 
STM 
STMCR 
RFM=l STMLF 
UDF 
VAR 
VFC 

RTV== window-size, 

SHR = <DEL GET MSE NIL PUT UPD UPI> 
XAB = xab-address 


For a description of the control block fields that correspond to the $FAB 
macro arguments, see Chapter 5. In some cases, specific default values are 
assigned automatically when you omit an argument. If there is no specific 
default, VMS RMS uses a default value of 0. 


Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 

Note that multiple arguments can be specified for the FAC, FOP, RAT, and 
SHR keywords, but the arguments must be enclosed within left angle ( <) 
and right angle (> ) brackets. The DNM and FNM arguments must also be 
delimited by these signs. 

The DNM and FNM arguments contain ASCII characters and have no 
corresponding field in the FAB. If the DNM argument is present, VMS RMS 
places its appropriate address and size in the FAB$L_DNA and FAB$B_ 
DNS fields. Similarly, if the FNM argument is present, VMS RMS places its 
appropriate address and size in the FAB$L_FNA and FAB$B__FNS fields. 
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VMS RMS Control Block Macros 

$FAB_ST0RE 


$FAB 


FORMAT 


STORE 

The $FAB_STORE macro moves user-specified values into fields of the 
specified FAB. The expanded $FAB_STORE code executes at run time 
on a previously initialized (allocated) FAB, in contrast to the $FAB macro, 
which initializes the FAB at assembly time. The $FAB_STORE macro must 
reside in a code program section. 


$FAB_STORE fab = fab-address, 

ALQ = ^allocation-quantity, 

BKS = ^bucket-size, 

BLS = ^block-size, 

CHAN—MODE=0channel-access-mode 
CTX= user-context-value, 

DEQ = ^extension-quantity, 

DNA = default-filespec-address, 

DNS = ffdefault-filespec-string-size, 

FAC = <BIO BRO DEL GET PUT TRN 
UPD> , 

FNA = filespec-string-address, 

FNS = 0filespec-string-size, 

<CBT CIF CTG DFW DL T 
MXV NAM NEF NFS OFP 
FOP = POS RCK RWCRWO SCF 
SPL SQO SUP TEF TMD 
TMPUFOWCK>, 

FSZ= ^header-size, 

GBC = ^global-buffer-count, 
LNM—MODE = ^logical-name- 

translation-access-mode, 
MRN= ffmaximum-record-number, 

MRS = #maximum-record-size, 

NAM=nam-address, 

(IDX ] 

ORG=Irel 

y SEQ ) 

Rat=}. <:blkftn> 1, 

y PRN j 
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ARGUMENTS 


FIX 
STM 
STMCR 
RFM=l STMLF 
UDF 
VAR 
VFC 

RTV= ^window-size, 

SHR = <DEL GET MSE NIL PUT UPD 
UPI> , 

XAB = xab-address 


For a description of the control block fields that correspond to the $FAB-> 
STORE macro arguments, see Chapter 5. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The FAB argument fab-address is required for the $FAB-_STORE macro and 
is not present for the $FAB macro. Conversely, the DNM argument filespec 
and FNM argument default-filespec are not available for the $FAB-_STORE 
macro, although you can use the DNA/DNS and FNA/FNS arguments to 
specify file specifications at run time. 

Note that RO is usually used by the $FAB_STORE macro; thus, RO is not 
preserved and does not contain a return status. 


B-5 






VMS RMS Control Block Macros 

$NAM 


$NAM 

The $NAM macro allocates storage for a NAM block and initializes certain 
NAM fields with default values and user-specified values. No value is 
returned for this assembly-time operation. 

FORMAT 

$NAM ESA = expanded-string-address, 

ESS = expanded-string-size, 

NOP - <noconceal PWD 

SRCHXABS SYNCHK> , 

RLE = related-file-nam-block-address, 

RSA = resultant-string-address, 

RSS = resultant-string-size 

ARGUMENTS 

For a description of the control block fields that correspond to the $NAM 
macro arguments, see Chapter 6. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 

Note that multiple arguments can be specified for the NOP keyword, but 
the arguments must be enclosed within left angle ( <) and right angle (> ) 
brackets. 
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$NAM_STORE 



The $NAM_STORE macro moves user-specified values into fields of the 
specified NAM block. The expanded $NAM_STORE code executes at 
run time on a previously initialized (allocated) NAM block, in contrast to 
the $NAM macro, which initializes a NAM block at assembly time. The 
$NAM_STORE macro must reside in a code program section. 

FORMAT 

$NAM_STORE NAM = nam-address, 

DID = ^directory-identification, 

DVI = ^device-identification, 

ESA = expanded-string-address, 

ESS = ffexpanded-string-size, 

FID = ^file-identification, 

NOP - <noconceal PWD 

SRCHXABS SYNCHK> , 

RLF = related-file-nam-block-address, 
RSA = resultant-string-address, 

RSS = resultant-string-size 

ARGUMENTS 

For a description of the control block fields that correspond to the $NAM_ 
STORE macro arguments, see Chapter 6. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The NAM argument nam-address is required for the $NAM__STORE macro 
and is not present for the $NAM macro. Also, the $NAM—STORE argument 
fields below are not available for the $NAM macro. 

• The DID argument directory-identification sets the NAM$W_DID field, 
which is a 3-word field used when the FAB$L_FOP field FAB$V_-NAM 
option is set. This argument is usually specified by its symbolic address. 

If a register is used to contain a value for the NAM$W_DID field, do 
not use R12, because two contiguous registers must be used to contain 
the value of this 3-word field. Note that you cannot use the byte, word, 
or longword displacements for an offset, or for indexed or deferred 
addressing. 

• The DVI argument device-identification sets the NAM$T__DVI field, 
which is a 16-byte field used when the FAB$L__FOP field FAB$V_NAM 
option is set. This argument must be passed by its symbolic address. A 
register must not be specified to contain a value for this argument. 
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• The FID argument file-identification sets the NAM$WL_FID field, which 
is a 3-word field used when the FAB$L_FOP field FAB$V_NAM option 
is set. This argument is specified by its symbolic address. If a register 
is used to contain a value for the NAM$W-_FID field, do not use R12, 
because two contiguous registers must be used to contain the value of 
this 3-word field. Note that you cannot use the byte, word, or longword 
displacements for an offset, or for indexed or deferred addressing. 

Note that RO is usually used by the $NAM^STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$RAB 


The $RAB macro allocates storage for a RAB and initializes certain RAB 
fields with defaults and user-specified values. You cannot use this macro 
within a sequence of executable instructions. No value is returned for this 
assembly-time operation. 


FORMAT 


$RAB BKT = bucket-code-number. 


CTX = user-context-value, 

FAB = fab-address, 

KBF= key-buffer-address, 

KF{F= key-of-reference-number, 
KSZ= key-size, 

MBC = multiblock-count-number, 
MBF= multibuffer-count-number, 
PBF = prompt-buffer-address, 
PSZ = prompt-buffer-size. 


RAC = 



y SEQ ) 

RBF= record-buffer-address, 

RHB = record-header-buffer-address, 

<ASY BIO CCO CVTEOF EQNXT 
ETO FDL KGE KGT LIM LOA 
ROP = LOC NLK NXR NXT PMT PTA 
RAH REA RLK RNE RNF RRL 
TMO TPT UIF ULK WAT WBH> , 
RSZ=record-size, 

TMO = time-out-number-of-seconds, 
UBF= user-record-buffer-address, 

USZ= user-record-buffer-size, 

XAB = xab-address 
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ARGUMENTS 


For a description of the control block fields that correspond to the $RAB 
macro arguments, see Chapter 7. In some cases, specific default values are 
assigned automatically when you omit an argument. These specific defaults 
are noted in the text that explains each field in Chapter 7. If there is no 
specific default, VMS RMS uses a default value of 0. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 

Note that multiple arguments can be specified for the ROP keyword, but 
the arguments must be enclosed within left angle ( <) and right angle 
(> ) brackets. Note too that the arguments KGE and EQNXT are logically 
synonymous, as are the arguments KGT and NXT. 
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$RAB 


FORMAT 


STORE 


The $RAB_STORE macro moves user-specified values into fields of the 
specified RAB. The expanded $RAB_STORE code executes at run time 
on a previously initialized (allocated) RAB, in contrast to the $RAB macro, 
which initializes the RAB at assembly time. The $RAB_STORE macro 
must reside in a code program section. 


$RAB_STORE RAB = rab-address, 

BKT= ^bucket-code-number, 

CTX = user-context-value, 

FAB = fab-address, 

KBF= key-buffer-address, 

KRF= ffkey-of-reference-number, 
KSZ= #key-size, 

MBC = 0multiblock-count-number, 
MBF= ^multibuffer-count-number, 
PBF=prompt-buffer-address, 

PSZ= prompt-buffer-size, 

RAC=l RFA > . 
i SEQ ) 

RBF=record-buffer-address, 

RFA = #record-file-address, 

RHB = record-header-buffer-address, 
<ASYBIOCCOCVT 
EOF EQNXT ETO FDL 
KGEKGTLIMLOA 
DQp ^LOC NLK NXR NXT 
PMTPTARAHREA 
RLKRNERNFRRL 
TMOTPTUIFULK 
WAT WBH> , 

RSZ= ^record-size, 

TMO = ^fi'^^'Out-number-of- 
seconds, 

UBF= user-record-buffer-address, 
USZ= user-record-buffer-size, 

XAB = xab-address 
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ARGUMENTS For a description of the control block fields that correspond to the $RAB_ 

STORE macro arguments, see Chapter 7. 


Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The RAB argument rab-address is required for the $RAB_STORE macro 
and is not present for the $RAB macro. Also, the RFA argument record- 
file-address is a value (not an address), and it is not available for the $RAB 
macro. The value for the 3-word RAB$W_RFA field must be set before each 
RFA record access. 

This argument is specified by its symbolic address. If a register is used to 
contain a value for the RAB$W_RFA field, do not use R12, because two 
contiguous registers must be used to contain the value of this 3-word field. 
Note that you cannot use the byte, word, or longword displacements for an 
offset, or for indexed or deferred addressing. 

Note that multiple arguments can be specified for the ROP keyword, but 
the arguments must be enclosed within left angle ( <) and right angle 
(> ) brackets. Note too, that the arguments KGE and EQNXT are logically 
synonymous as are the arguments KGT and NXT. 

Note that RO is usually used by the $RAB_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABALL 


The $XABALL macro allocates and initializes an XABALL, which allows 
extended control of file disk space allocation, both for initial allocation and 
later extension. No value is returned for this assembly-time operation. 


FORMAT 


$XABALL 


AID = area-identification-number. 


ALN-I 


ANY 

CYL 

LBN > . 
RFI 

VBN J 


ALQ = allocation-quantity, 


AOP = CTG 
HRDONO, 

BKZ= bucket-size, 

DEQ = extension-quantity, 
LOG = location-number, 
NXT = next-xab-address, 
RFI = <f(1), f(2), f(3)> , 
VOL = volume-number 


ARGUMENTS 


For a description of the control block fields that correspond to the $XABALL 
macro arguments, see Chapter 8. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 

Note that multiple arguments can be specified for the AOP keyword, but 
the arguments must be enclosed within left angle ( <) and right angle (> ) 
brackets. 
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$XABALL_STORE 


The $XABALI_STORE macro moves user-specified values into fields of 

the specified XABALL. The expanded SXABALI_STORE code executes 

at run time on a previously initialized (allocated) XABALL, in contrast to 
the SXABALL macro, which initializes an XABALL at assembly time. The 
SXABALI_STORE macro must reside in a code program section. 


FORMAT 


$XABALL_STORE 


XAB = xaball-address, 

AID = ^area-identification-number, 
ANY 
CYL 

ALN=l iBN 
RFI 
VBN 

ALQ = ^allocation-quantity, 

AQP = DTG 

HRD ONO , 


BKZ= ^bucket-size, 

DEQ = ^extension-quantity, 
LOG = ^location-number, 

NXT= next-xab-address, 

RFI=#related-file-identification, 
VOL = ^volume-number 


ARGUMENTS For a description of the control block fields that correspond to the SXABALL _ 

STORE macro arguments, see Chapter 8. 

Arguments fall into several categories: value, address, keyword, and the 
address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros 
are described in Chapter 3. 

The XAB argument xaball-address is required for the SXABALL—STORE 
macro and is not present for the SXABALL macro. Also, the RFI argument 
related file identification sets the XABSW_RF1 field, which is a 3-word field 
used when the XABSB—ALN field XABSV_RF1 option is set. This argument 
is usually specified by its symbolic address. If a register is used to contain 
a value for the XABSW—RFI field, do not use R12, because two contiguous 
registers must be used to contain the value of this 3-word field. Note that 
you cannot use the byte, word, or longword displacements for an offset, or 
for indexed or deferred addressing. 

Note that RO is usually used by the SXABALL—STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABDAT 

The $XABDAT macro allocates and initializes an XABDAT. No value is 
returned for this assembly-time operation. 

FORMAT 

$XABDAT EDT = date-time, 

NXT= next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABDAT 
macro arguments, see Chapter 8. 

Rules applicable to arguments are described in Chapter 3. 
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$XABDAT_STORE 

The $XABDAT_STORE macro moves user-specified values into fields of 
the specified XABDAT. The expanded $XABDAT_STORE code executes 
at run time on a previously initialized (allocated) XABDAT, in contrast to 
the $XABDAT macro, which initializes an XABDAT at assembly time. The 
$XABDAT_STORE macro must reside in a code program section. 


FORMAT $XABDAT_STORE XAB = xabdat-address, 

CDT= #creation-date-time, 
EOT = ^expiration-date-time, 
RDT= ^revision-date-time, 
RVN=Prevision-number, 
NXT = next-xab-address 


ARGUMENTS For a description of the control block fields that correspond to the $XABDAT_ 

STORE macro arguments, see Chapter 8. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The XAB argument xabdat-address is required for the $XABDAT_STORE 
macro and is not present for the $XABDAT macro. Also, the arguments 
below differ from the general rules. 

• The CDT argument creation-date-time sets the XAB$Q_CDT field, 
which is a quadword field. However, if a register is used to contain a 
literal value for the XAB$Q_CDT field, do not use R12, because two 
contiguous registers must be used to contain the value of this quadword 
field. 

• The EDT argument expiration-date-time sets the XAB$Q_EDT field, 
which is a quadword field. The rules for the other time fields (see above) 
also apply to this one. 

• The RDT argument revision-date-time sets the XAB$Q_CDT field, 
which is a quadword field. The rules for the other time fields (see above) 
also apply to this one. 

Note that RO is usually used by the $XABDAT_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABFHC 

The $XABFHC macro allocates and initializes an XABFHC. No value is 
returned for this assembly-time operation. 

FORMAT 

$XABFHC NXT = next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABFHC 
macro arguments, see Chapter 10. 

Rules applicable to arguments are described in Chapter 3. 
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$XABFHC_STORE 

The $XABFHC_STORE macro moves user-specified values into fields of 
the specified XABFHC. The expanded $XABFHC_STORE code executes 
at run time on a previously initialized (allocated) XABFHC, in contrast to 
the $XABFHC macro, which initializes an XABFHC at assembly time. The 
$XABFHC_STORE macro must reside in a code program section. 


FORMAT $XABFHC_STORE XAB = xabfhc-address, 

NXT= next-xab-address 


ARGUMENTS For a description of the control block fields that correspond to the $XABFHC_ 

STORE macro arguments, see Chapter 10. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The XAB argument xabfhc-address is required for the $XABFHC_STORE 
macro and is not present for the $XABFHC macro. 

Note that RO may be used by the $XABFHC_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABITM 

The $XABITM macro allocates and initializes an XABITM. No value is 
returned for this assembly-time operation. 

FORMAT 

$XABITM ITEMLIST= item-list-address, 

MODE=i sensemode 1 ^ 

1 setmode / ' 

NXT = next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABITM 
macro arguments, see Chapter 11. 

Rules applicable to arguments are described in Chapter 3. 

ITEMLIST defaults to 0 but a valid pointer must be specified when you use a 
$XABITM macro. MODE defaults to sensemode. 
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$XABKEY 


The $XABKEY macro allocates and initializes an XABKEY. No value is 
returned for this assembly-time operation. 


FORMAT 


SXABKEY 


COLTBL = collating-table-address, 
DAN= data-bucket-area-number, 
DFL = data-bucket-fill-size, 

BN2 
DBN2 
BN4 
DBN4 
BN8 
DBN8 
IN2 
DIN2 
IN4 
DIN4 
IN8 
DIN8 
COL 
DCOL 
PAC 
DPAC 
STG 
DSTG 

<CHG DAT-NCMPR DUP 
FLG- IDX^NCMPR 


DTP = 


KEY^NCMPR NUL> , 

IAN = index-bucket-area-number, 

IFL = index-bucket-file-size, 

KNM = key-name-buffer-address, 

LAN = lowest-level-index-area-number, 
NUL = null-key-value, 

NXT= next-xab-address, 

POS = <position,...> , 

PROLOG = prolog-level, 

REF = key-of-reference-value, 
SIZ=<size,...> 
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ARGUMENTS 


For a description of the control block fields that correspond to the $XABKEY 
macro arguments, see Chapter 13. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 

Multiple arguments can be specified for the FLG keyword, but the arguments 
must be enclosed within left angle ( <) and right angle (> ) brackets. 
Defaults are applied to the XAB$B—FLG field only if no FLG argument is 
specified. Consider the following: 

KEY_1: $XABKEY REF = 1, POS = 0, SIZ = 10 

This line specifies the key for alternate index 1. Therefore the macro defaults 
the XAB$B__FLG field to allow duplicates and changes (the default for 
alternate keys). However, if an FLG argument is explicitly specified, the 
results are different, as shown below. 

KEY_2: SXABKEY REF = 1, POS = 0, SIZ = 10, FLG = CHG 

In this case, the CHG bit is set in the XAB$B_FLG field and the DUP bit 
remains clear, to disallow duplicates on this key. 

Depending on whether the key being defined is simple or segmented, you 
would use one of the following two formats for the POS and SIZ arguments: 

POS = position 


SIZ = size 
or 

POS =<position0,...,position7> 


SIZ =<size0,...,size7> 

You must include the angle brackets for multiple argument key positions and 
sizes. 
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$XABKEY_STORE 


The $XABKEY_STORE macro moves user-specified values into fields of 
the specified XABKEY. The expanded $XABKEY_STORE code executes 
at run time on a previously initialized (allocated) XABKEY, in contrast to 
the $XABKEY macro, which initializes the XABKEY at assembly time. The 
$XABKEY_STORE macro must reside in a code program section. 


FORMAT 


$XABKEY_STORE 


XAB = xabkey-address, 

COLTBL = ^collating-table-address, 
DAN=^data-bucket-area-number. 


DTP=l 


DFL = #data-bucket-fill-size, 
BN2 
DBN2 
BN4 
DBN4 
BN8 
DBN8 
IN2 
DIN2 
IN4 
DIN4 
IN8 
DIN8 
COL 
DCOL 
PAC 
DPAC 
STG 
DSTG 
<CHG DAT-NCMPR 
FLG = DUPIDX-NCMPR 
KEY-NCMPR NUL> . 


IAN= ^'f^dex-bucket- 
area-number, 

IFL = #index-bucket-fill-size, 
KNM= l<^y-f^3me-buffer- 
address, 

#lowest-level-index- 

area-number, 

NUL = #null-key-value, 
NXT= next-xab-address. 
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ARGUMENTS 


POS = <position,...> , 
PROLOG = ^prolog-level, 

REF = #key-of-reference-value, 
SIZ = <size,...> 


For a description of the control block fields that correspond to the $XABKEY_ 
STORE macro arguments, see Chapter 13. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The XAB argument xabkey-address is required for the $XABKEY__STORE 
macro and is not present for the $XABKEY macro.. The POS and SIZ 
arguments can be either symbolic addresses or a list of up to eight 
values, where each value must be preceded by a number sign (#), and 
the entire list must be enclosed within left angle and right angle brackets 
( <#value,...,#value> ). The number of POS and SIZ values must be equal. 
Alternatively, each POS and SIZ value can be specified as an argument, using 
the following form: 

POSO = #value. POSl = #value. .... P0S7 = #value 

SIZO = #value, SIZl = #value, .... SIZ7 = #value 

Note that RO is usually used by the $XABKEY—STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABPRO 

The $XABPRO macro allocates and initializes an XABPRO. No value is 
returned for this assembly-time operation. 

FORMAT 

$XABPRO ACLBUF= ACL-buffer-address, 

ACLCTX = <ACL-context> , 

ACLSIZ= ACL-buffer-size, 

MTACC = ^^9^^tic-tape- 
accessibility, 

NXT=next-xab-address, 

Pf^Q = <system, owner, 
group, world>, 

PROT-OPT=<PROPAGATE> , 

UlC = <group, member> 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABPRO 
macro arguments, refer to Chapter 14. 

Rules applicable to arguments are described in Chapter 3. 

For the MTACC argument, an ASCII radix indicator is required. For example, 
the letter Z is entered as the accessibility character with the following macro 
expression: 

$XABPR0 MTACC = ‘A/Z/ 

In this example, the circumflex ( ' ) followed by an uppercase A ("A) indicates 
that ASCII text follows. The two slashes (//) delimit the ASCII text. VMS 
RMS converts all lowercase characters to uppercase. No other modification is 
made. 

For the PRO argument, the angle brackets are required syntax, and each 
user class must be separated from the others by a comma. When you omit a 
class to use the default protection, you must retain the comma to indicate the 
omission, unless no other class follows. 

To allow all system users read and write access, use the default file protection 
for the file owner (by omission), allow group users read access, and use the 
default for world users, you would specify <RW„R> . You may specify all, 
some, or none of the access characters and place multiple characters in any 
order, for each user class. 
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Here is a listing of the user classes together with the letters used to represent 
them: 

• R—read access 

• W—write access 

• E—execute access 

• D—delete access 

The absence of a code specifies that the access associated with the code is 
denied to the user. 

A user is granted the maximum number of access rights for each of the classes 
to which he belongs. 

For the UIC argument, the value for the group item must be in the range 
of 0 to 37777; the value for the member item must from 0 to 177777. Note 
that the maximum values (37777 and 177777) are reserved for DIGITAL use 
only. The group number and member number must be enclosed within angle 
brackets, placed in the order <group,member> , and be separated by a 
comma. Each number is interpreted as an octal number. 
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$XABPRO_STORE 


The $XABPRO_STORE macro moves user-specified values into fields of 
the specified XABPRO. The expanded $XABPRO_STORE code executes 
at run time on a previously initialized (allocated) XABPRO, in contrast to 
the $XABPRO macro, which initializes an XABPRO at assembly time. The 
$XABPRO_STORE macro must reside in a code program section. 


FORMAT 


$XABPRO_STORE 


XAB = xabpro-address, 
ACLBUF= ACL-buffer-address, 
ACLCTX = ^<ACL-context> , 
ACLSIZ= #ACL-buffer-size, 

I\/I1~/\QQ = ^i^39ri6tic~tap6~ 

accessibility, 

NXT= next-xab-address, 
PPQ=<system, owner, 
group, world> , 
PFIOT-OPT=< PROPAGATE > 
UlC = #uic-value 




ARGUMENTS For a description of the control block fields that correspond to the $XABPRO_ 

STORE macro arguments, see Chapter 14. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The XAB argument xabpro-address is required for the $XABPRO_STORE 
macro and is not present for the $XABPRO macro. Also, the following 
arguments do not comply with the general rules: 

• The PRO argument (file protection) can be either a symbolic address 
or a list of keyword values. If you specify a list of keywords, it 
must be enclosed within left angle ( <) and right angle (> ) brackets 
and the number sign (#) must be omitted; for example, PRO = 

<RWED,RWED,R,R> . 

• The UlC argument (group,member) can be either a symbolic address 
or a list of two data values. If the data values are constants, they must 
be specified with an octal radix without a preceding number sign (#). 
This argument can be passed by its symbolic address or by using a VAX 
MACRO expression. 

Note that RO is usually used by the $XABPRO_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABRDT 

The $XABRDT macro allocates and initializes an XABRDT. No value is 
returned for this assembly-time operation. 

FORMAT 

$X A B R DT NXT = next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABRDT 
macro argument, see Chapter 15. 

Rules applicable to arguments are described in Chapter 3. 
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$XABRDT_STORE 



The $XABRDT_STORE macro moves user-specified values into fields of 
the specified XABRDT. The expanded $XABRDT_STORE code executes 
at run time on a previously initialized (allocated) XABRDT, in contrast to 
the $XABRDT macro, which initializes the XABRDT at assembly time. The 
$XABRDT_STORE macro must reside in a code program section. 

FORMAT 

$X A B R DT_ST ORE XA B = xabrdt-address, 

RDT = ^revision-date-time, 

RVN = Prevision-number, 

NXT= next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABRDT_ 
STORE macro arguments, see Chapter 15. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The XAB argument xabrdt-address is required for the $XABRDT_STORE 
macro and is not present for the $XABRDT macro. Also, the RDT argument 
revision-date-time and RVN argument revision-number are not present 
in the $XABRDT macro. The RDT argument revision-date-time is usually 
passed by its symbolic address. However, if a register is used to contain a 
value for the XAB$Q_RDT field, do not use R12, because two contiguous 
registers must be used to contain the value of this quadword field. 

Note that RO is usually used by the $XABRDT_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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SXABSUM 

The $XABSUM macro allocates and initializes an XABSUM. No value is 
returned for this assembly-time operation. 

FORMAT 

$XABSUM NXT = next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABSUM 
macro argument, see Chapter 17. 

Rules applicable to arguments are described in Chapter 3. 
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$XABSUM. 

-STORE 

The $XABSUM_STORE macro moves user-specified values into fields of 
the specified XABSUM. The expanded $XABSUM_STORE code executes 
at run time on a previously initialized (allocated) XABSUM, in contrast to 
the SXABSUM macro, which initializes the XABSUM at assembly time. 

The $XABSUM_STORE macro must reside in a code program section. 

FORMAT 

SXABSUM—STORE XAB = xabsum-address, 

NXT== next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the 
SXABSUM—STORE macro arguments, see Chapter 17. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 

The XAB argument xabsum-address is required for the $XABSUM—STORE 
macro and is not present for the $XABSUM macro. 

Note that RO may be used by the $XABSUM—STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABTRM 

The SXABTRM macro allocates and initializes an XABTRM. No value is 
returned for this assembly-time operation. 

FORMAT 

$XABTRM ITMLST= item-list-address, 

ITMLST-.LEN = item-list-length, 

NXT= next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABTRM 
macro arguments, see Chapter 18. 

Rules applicable to arguments are described in Chapter 3. 
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$XABTRM_STORE 


The $XABTRM_STORE macro moves user-specified values into fields of 
the specified XABTRM. The expanded $XABTRM_STORE code executes 
at run time on a previously initialized (allocated) XABTRM, in contrast to 
the $XABTRM macro, which initializes an XABTRM at assembly time. The 
$XABTRM_STORE macro must reside in a code program section. 


FORMAT $XABTRM_STORE XAB = xabtrm-address, 

ITMLST= item-list-address, 
ITMLST—LEN = ^item-list-length, 
NXT= next-xab-address 


ARGUMENTS For a description of the control block fields that correspond to the 

$XABTRM—STORE macro arguments, see Chapter 18. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
. applicable to these argument categories for the control block store macros are 

described in Chapter 3. 

The XAB argument xabtrm-address is required for the $XABTRM—STORE 
macro and is not present for the $XABTRM macro. 

Note that RO is usually used by the $XABTRM—STORE macro; thus, RO is 
not preserved and does not contain a return status. 
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Access 

modes* 1-1 
run-time options* 1-2 
Access control list 
See ACL 

Access control list buffer field 
See XAB$L_ACLBUF field 
Access control list buffer size field 
See XAB$W_ACLSIZ field 
Access control list context field 
See XAB$L_ACLCTX field 
Access control list error status field 
See XAB$L_ACLSTS field 
Access control list length field 
See XAB$W_ACLLEN field 
Access specification 

list of mask values* 14-6 
ACE (access control list) 

VMS RMS limitation* 14-2 
ACL (access control list) 
conversion methods* 14-2 
use with VMS RMS control block* 14-2 
Actual offset value 
avoiding use of *2-4 
Alignment boundary type field 
See XAB$B_ALN field 
Allocation control extended address block 
See XABALL block 
Allocation options field 
See XAB$B_AOP field 
Allocation quantity field 
See FAB$L_ALQ field 
Area allocation quantity field 
See XAB$L_ALQ field 
Area default extension quantity field 
See XAB$W_DEQ field 
Area identification number (AID) 
program example *4-8 
Area identification number field 
See XAB$B_AID field 
Argument 

delimiters *3-10 


Argument (cont'd.) 

initialization and control block store macros* 
3-8 

passing* 1-2 
separator *3-6 

specifying as run-time values *3-9 
to FAB* 1-2 
to RAB* 1-4 
Argument keyword 

delimiting for service *3-10 
Argument list 
count field * 2-5 
description * 2-4 
error routine address field *2-5 
new FAB address field *2-5 
passing to service *3-10 
success routine address field *2-5 
ASCII character 

delimiting in control block fields *3-6, 3-7 
Asynchronous I/O option 
See FAB$V_ASY 
See RAB$V_ASY option 
Asynchronous operation 

contrasted with synchronous operation * 2-7 
using R0*2-5 
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Backup date and time field 
See XAB$Q_BDT field 
BID field 

See Block identifier field 
BLN field 

See Block length field 
Block boundary option 
See FAB$V_BLK option 
Block code field 

See XAB$B_COD field 
Block I/O 

additional services that use *4-23 
applicable services *4-23 
description *4-23 
how to execute * 4-24 
how to specify for relative and indexed files * 
4-24 
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Block I/O (cont'd.) 

program example •4-25 

requirements for mixing with record 1/0*4-23 

restrictions to *4-23 

services *3-5 

specifying *4-23 

use of NBP for sequential files *4-25 
with multiple record streams *4-25 
with record I/O processing *4-25 
Block I/O execution 

contrasted with record I/O execution *4-24 
Block I/O option 

See FAB$V_BI0 option 
See RAB$V_BI0 option 
Block identifier field 
See FAB$B_BID field 
See NAM$B_BID field 
See RAB$B_BID field 
Block length field 

See NAM$B_BLN field 
Block length field In allocation XAB 
See XAB$B_BLN field 
Block length field In date and time XAB 
See XAB$B_BLN field 
Block length field In file access block 
See FAB$B_BLN field 

Block length field in file header characteristics XAB 
See XAB$B_BLN field 
Block length field In Item list XAB 
See XAB$B_BLN field 
Block length field in key XAB 
See XAB$B_BLN field 
Block length field In protection XAB 
See XAB$B_BLN field 
Block length field In record access block 
See RAB$B_BLN field 

Block length field in revision date and time XAB 
See XAB$B_BLN field 
Block length field in summary XAB 
See XAB$B_BLN field 
Block length field in terminal XAB 
See XAB$B_BLN field 
Block or record I/O option 
See FAB$V_BRO option 
Bucket boundary 

file organization considerations*5-4 
Bucket code field 

See RAB$L_BKT field 


Bucket size field 

See FAB$B_BKS field 
Bucket size field in allocation XAB 
See XAB$B_BKZ field 

Bucket size field in file header characteristics XAB 
See XAB$B_BKZ field 
Bucket split 

minimizing* 13-4 
BYTLM quota 

limiting size of user's ACL buffer* 14-3 
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Caller access mode *5-5 
Calling sequence *2-4 
Calling services* 1-1 
Cancel CTRL/0 option 
See RAB$V_CCO option 
Carriage return option 
See FAB$V_CR option 
CDT argument *B-16 

Channel access mode protection option *5-5 
Channel access mode subfield 
See FAB$V_CHAN_MODE 
See FAB$V_CHAN_MODE subfield 
CHG (change) option 

in XAB$B_FLG field *B-21 
Close service 

condition values*RMS-5 

See also Completion status codes 
contrasted with Disconnect service *4-5 
control block input fields*RMS-4 
control block output fields * RMS-4 
function *4-1 
introduction *4-1 
limitations with XABs* RMS-4 
use restrictions * RMS-4 
Collating key data type* 13-6 
Collating sequence name field 
See XAB$L_COLNAM field 
Collating sequence size field 
See XAB$L_COLSIZ field 
Collating sequence table field 
See XAB$L_COLTBL field 
Comment separator *3-6 
Completion routine 

condition for AST execution *3-11 
service macro arguments *3-11 
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Completion status code 

description *2-5, A-9 to A-20 
errors for inaccessible control block condition* 
2-6 

handling *3-12 

hexadecimal values* A-2 to A-9 
listing conditions when not returned* A-2 
severity codes * 2-6 
testing *2-5 

Completion status code field 
use with debugger* A-2 
Completion status code field in FAB 
See FAB$L_STS field 
Completion status code field In RAB 
See RAB$L_STS field 
Completion status code value field 
use with debugger* A-2 
Completion status field 

See also FAB$I_STS field 

as alternative to use of R0*2-4 
for signaling errors *2-6 
Completion status value field 
as alternative to use of R0*2-4 
for signaling errors *2-6 
Completion status value field In FAB 
See FAB$L_STV field 
Completion status value field in RAB 
See RAB$L_STV field 
Condition value 

See Completion status code 
Connect service * RMS-6 

comparing positioning for various file 
organizations* RMS-7 
condition values*RMS-9 
connecting record stream *4-4 
control block input fields*RMS-7 
control block output fields*RMS-8 
program example *4-12 
use with multiple keys *4-12 
Contiguous best try option 
See FAB$V_CBT option 
Contiguous option 

See also FAB$V_CTG option 
See FAB$V_CTG option 
Continuation character *3-6 
Control block 

dual purpose* 1-4 
field name conventions *2-2 
for extended attributes* 1-3 
for file name operations* 1-3 
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for file services* 1-2 
for record services* 1-4 
macro names *3-2 

requirements for valid default values* 1-4 
symbolic bit offset * 2-4 
symbolic constant (keyword) value *2-4 
symbolic naming exceptions *2-3 
symbolic offsets * 2-2 
types of macros *3-1 
use restrictions *2-1 
use with VAX languages *2-1 
Control block store macro 
description *3-1 
example *3-9 
placement guidelines *3-8 
requirement for number sign *3-8 
use of R0*3-8 
Control routine *4-27 
CONVERT command *4-9 
Convert option 

See RAB$V_CVT option 
CREATE/FDL command *4-9 
Create-if option *4-1 

See also FAB$V_CIF option 
$CREATE macro *3—10 
Create service*RMS-10 
condition values*RMS-19 
contrasted with Open service *4-1 
control block Input fields*RMS-11 
control block output fields*RMS-15 
function *4-1 

handling search list*RMS-11 
Invoking *4-1 
program example *4-2 
Prolog level*RMS-18 
using the create-if option*RMS-17 
using the NAM block*RMS-16 
using to create indexed files*RMS-18 
XAB override in various fields*RMS-11 
Creation date and time field 
See XAB$Q_CDT field 
CTRL/Z 

using as end-of-file marker*RMS-49 
using to terminate Get service * RMS-49 
Current position option 
See FAB$V_POS option 
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DAP (data access protocol)* 1-1 
Data access protocol 
See DAP 

Data bucket area number (DAN) 
program example *4-8 
Data bucket area number field 
See XAB$B_DAN field 
Data bucket fill size (DFL) 
program example *4-8 
Data bucket fill size field 
See XAB$W_DFL field 
Data bucket size field 
See XAB$B_DBS field 
Data level 

comparing for primary and altej'nate keys* 13-4 
Data type of key field 
See XAB$B_DTP field 
Date and time extended address lj)lock 
See XABDAT block 
Debugger 

use with completion status c^cjles* A-2 
DEC Multinational Character Set 
using *2-7 

DECnet remote file access 

specifying maximum record siz^*5-22 
Default extension quantity field 
See FAB$W_DEQ field 

Default file extension quantity fiel(|J in XABFHC 
See XAB$W_DXQ field 
Default file specification string address field 
See FAB$L_DNA field 
Default file specification string size field 
See FAB$B_DNS field 
Default global buffer count field 
See XAB$W_GBC field 
Deferred write option 

See FAB$V_DFW option 
Delete on close option 
See FAB$V_DLT option 
Delete service * RMS-21 
condition values*RMS-22 

See also Completion status codes 
control block input fields*RMS-22 
control block output fields*RMS-22 
program example *4-19 
requirements * RMS-22 
use restrictions*RMS-21 


Delete service option 
See FAB$V_DEL option 
Delete sharing option 

See FAB$V_SHRDEL option 
Delimiter 

using in control block arguments *3-5, 3-6, 
3-7 

SDEVDEF macro 

source of DEV field bit definitions*5-7 
Device characteristics field 
See FAB$L_DEV field 
Device identification field 
See NAM$T_DVI field 
Device name address descriptor 
See NAM$L_DEV descriptor 
Device name address field 
See NAM$L_DEV field 
Device name length field 
See NAM$B_DEV field 
Device name size descriptor 
See NAM$B_DEV descriptor 
Directory address descriptor 
See NAM$L_DIR descriptor 
Directory identification field 
See NAM$W_DID 
Directory name length address field 
See NAM$L_DIR field 
Directory name length field 
See NAM$B_DIR field 
Directory size descriptor 

See NAM$B_DIR descriptor 
Disconnect service*RMS-23 
condition values*RMS-24 

See also Completion status codes 
control block input fields*RMS-24 
control block output fields * RMS-24 
program example *4-12 
using with multiple RABs* RMS-24 
Disk cluster boundary 

determining allocation quantity *5-3 
Display service*RMS-25 
condition values*RMS-28 
control block Input fields*RMS-26 
control block output fields*RMS-26 
requirements * RMS-26 
DNA (default name address) argument *B-5 
DNM (default name) argument *B-3 
DNM (default name) field *4-3 
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DNM (default name) keyword 

specifying FAB$I_DNA and FAB$B_DNS fields 

from VAX MACRO* 5-9 
DNS (default name size) argument •B-B 
DUP (duplicate) option 

in XAB$B_FLG field •B-21 
Duplicate key 
examples *7-8 

incompatibility between VMS RMS and RMS-11 
•13-9 

insertion order •RMS-72 
retrieving records • 7-8 
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EDT argument *8-16 
End-of-file field In XABFHC 
See XAB$L_EBK field 
End-of-flle mark 

positioning for user file open option *5-18 
End-of-file option 

See RAB$V_EOF option 
End-of-file positioning •RMS-7 
Enter service*RMS-29 
condition values*RMS-31 
control block Input fields •RMS-30 
control block output fields*RMS-30 
requirement for NAM block fields*RMS-30 
Erase service*RMS-32 
alternative * RMS-33 
condition values*RMS-34 

See also Completion status codes 
control block Input fields*RMS-33 
control block output fields*RMS-33 
requirements for using*RMS-33 
use restriction*RMS-33 
Error 

recommended method for signaling *2-6 
Error completion routine *2-5 
Error status code *2-6 

from Invalid control blocks *2-6 
Escape sequence 

using from terminal devices*RMS-49 
ETO (extended terminal operation) option* 
RMS-49 
Event flag 

for synchronous operations*2-7 
Executive-mode (PSL$C_EXEC) constant 
for FAB$V_CHAN_MODE*5-5 


Expanded string 
requesting *6-2 

Expanded string area address (ESA) 
program example *4-12 
Expanded string area address field 
See NAM$L_ESA field 
Expanded string length field 
See NAM$B_ESL field 
Expanded string size field 
See NAM$B_ESS field 
Expiration date field 
See XAB$Q_EDT field 
Extended attribute block 
See XAB block 

Extended attribute block address field 
See FAB$L_XAB field 
See RAB$L_XAB field 
Extended terminal operation option 
See RAB$V_ETO option 
Extend service*RMS-35 
condition values*RMS-37 
control block Input fields*RMS-36 
control block output fields*RMS-36 
invoking *5-11 
requirements * RMS-36 
use restriction * RMS-36 
XAB overrides*RMS-36 
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FAB$B_ACMODES 

See FAB$V_CHAN_MODE and FAB$V_LNM_ 
MODE 

FAB$B_BID field *5-3 
FAB$B_BKS field *5-3 

considerations for calculating*5-4 
default logic *5-4 
limitation for RMS-11 *5-3 
performance considerations *5-4 
requirements for RMS-11 compatibility *5-5 
selecting default size for Indexed files *5-4 
variations for XABs*5-4 
FAB$B_BLrsf field *5-4 
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specifying default file specification * 5-2 
FAB$B_FAC field *5-9 

comparing with FAB$B_SHR field *5-9 
for specifying sharing options *4-1 
Interdependency with FAB$B_SHR field *5-27 
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options *5-10 

use with FAB$B_SHR* 5-10 
FAB$B_FNSfield*5-12 


specifying primary file specificfiition • 5-2 


FAB$B_FSZ field*5-18 
FAB$B_ORG field *5-23 
options* 5-23 

use by various services *5-23 
FAB$B_RAT field *5-23 
default logic *5-23 
options *5-23 
FAB$B_RFM field *5-25 


keywords *5-25 | 

options *5-25 
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with I/O channel*RMS-16 
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use restriction *5-14 
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how used to specify I/O type *4-24 
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FAB$V_BRO option 
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requirement for read-only buffer cache *5-20, 
5-28 


Index-6 








Index 







FAB$V_MSE option (cont'd.) 

use with other options *5-28 
FAB$V_MXV option *5-15 
FAB$V_NAM option*5-16 
FAB$V_NEF opti6n*5-17 
FAB$V_NFS option *5-18 

relationship to CHAN_MODE subfield*5-5 
FAB$V_NIL option *5-28 

effect on specifying user file open option *5-18 
precedence over other options *5-28 
requirement for block 1/0*4-23 
FAB$V_OFP option *5-16 
FAB$V_POS option *5-17 

subordinate to FAB$V_RWO option *5-17, 
5-18 

FAB$V_PRN option *5-24 

restriction against use with FAB$V_FTN and 
FAB$V_CR options* 5-23 
FAB$V_PUT option *5-11, 5-28 
use with block I/O operations*5-10 
FAB$V_RCK option *5-15 
restricted use *5-15 
FAB$V_RWC option *5-17 
FAB$V_RW0 option *5-17 

precedence over FAB$V_P0S option *5-17, 
5-18 

FAB$V_SCF option *5-16 

qualified use by Close service * RI\/lS-4 
use restriction *5-16 
FAB$V_SHRDEL option *5-28 
FAB$V_SHRGET option 
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effect on Internal structures * 5-20 
relationship to CHAN_MODE subfield *5-5 
FAB$V_UPD option *5-11, 5-28 

requirement for implementing update-if option* 
7-17 

requirement for Update service *4-22 
FAB$V_UPI option *5-28 
reqlrement for setting * 5-29 
requirement for block 1/0*4-23 
requirement for user file open option *5-18 
FAB$V_WCK option *5-15 
restricted use *5-15 
FAB$W_BLS field *5-5 
limitation *5-5 
setting * 5-5 

FAB$W_DEQ field *5-4, 5-6 
default logic * 5-6 
overriding default * 5-7 
FAB$W_GBC field *5-19 
as output *5-19 
changing *5-19 
clearing *5-19 
overriding default *5-19 
FAB$W_IFI field *5-20 
FAB$W_MRS field *5-21 
as output *5-22 
program example *4-4 
summary *5-22 

use with fixed-length records *5-21 
use with variable-length records *5-21 
FAB (file access block) *5-1 
argument categories* 1-2 
description* 1-2 
requirements for* 5-2 
summary of fields * 5-1 
$FAB macro *B-2 

argument categories * B-3 
$FAB_ST0RE macro *B-4 
argument categories*B-5 
FAB argument requirement*B-5 
run-time arguments*B-5 
FAC field 

See FAB$B_FAC field 
Fast delete option 

See RAB$V_FDL option 
FDL$PARSE*4-9 
FDL$RELEASE*4-9 
FDL Editor 

as alternative to multiple XABs in example *4-9 
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Field length 

identifier in symbolic name •2-3 
File 

characteristics argument for FAB* 1-2 
organizations* 1-1 
specification argument for FAB* 1-2 
File access block 
See FAB 

File access block address field 
See RAB$L_FAB field 
File access field 

See FAB$B_FAC field 
File component descriptor 
address field *6-3 
example *6-4 
field value logic * 6-3 
list of *6-3 
size field * 6-3 
suggested use of *6-4 
File Definition Language Editor 
See FDL Editor 
File extension 

using Extend service*RMS-36 
File header characteristic extended address block 
See XABFHC 
See XABFHC block 
File identification field 
See NAM$W_FID field 
File name address descriptor 

See NAM$I_NAME descriptor 

File name address field 
See NAM$L_NAME field 
File name length field 

See NAM$B_NAME field 
File name size descriptor 

See NAM$B_NAME descriptor 
File name status field 
See NAM$L_FNB field 
File name string 

component parts *4-9 
File name string address( FAB$L_FNA) field 
how used to specify file name string * 4-9 
File name string size (FAB$B_FNS) field 
how used to specify file name size *4-9 
File organization and record format field 
See XAB$B_RFO field 
File organization field 
See FAB$B_ORG field 
File owner group number field 
See XAB$W_GRP field 


File owner group number field (cont'd.) 

In XABPRO field *14-4 
File owner member number field 
See XAB$W_MBM field 
File positioning 

effect on shared files*RMS-7 
File-processing 

services listed * 3-3 
File-processing option 
as service output *5-12 
categories listed *5-12 
naming convention * 5-12 
File-processing options field 
See FAB$L_FOP field 
File protection extended address block 
See XABPRO block 
File protection field 

See XAB$W_PRO field 
File protection option field 
See XAB$B_PROT_OPT field 
File section 

defining in context of multiple volumes* 
RMS-56 
File sharing 
features* 1-1 
File sharing field 

See FAB$B_SHR field 
File specification 

component descriptors *6-2 
default requirements *4-9 
how handled by Search service *4-9 
parsing* RMS-66 
File specification address 
See FAB$L_FNA field 
File specification size 
See FAB$B_FNS field 
File specification string address *4-9 
File specification string size *4-9 
File type address descriptor 

See NAM$I_TYPE descriptor 

File type address field 
See NAM$L_TYPE field 
File type length field 

See NAM$B_TYPE field 
File type size descriptor 

See NAM$B_TYPE descriptor 
File version address descriptor 

See NAM$I_VER descriptor 

File version address field 
See NAM$L_VER field 
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File version length field 
See NAM$B_VER field 
File version limit field 

See XAB$W_VERLIMIT field 
File version size descriptor 
See NAM$B_VER descriptor 
Fill level 

comparing primary key and alternate keys* 
13-10 

Find service •RMS-38 
capabilities • RMS-39 
condition values •RMS-41 
control block input fields*RMS-39 
control block output fields*RMS-41 
First data bucket start virtual block number field 
See XAB$L_DVB field 
First free byte field 

See XAB$W_FFB field 
Fixed-length control area size field 
See FAB$B_FSZ field 
Fixed-length header control size field 
See XAB$B_HSZ field 
Fixed-length record format option 
See FAB$C_FIX option 
Flush service*RMS-43, RMS-44 
condition values*RMS-44 

See also Completion status codes 
control block Input fields*RMS-44 
control block output fields*RMS-44 
FNA argument *B-5 
FNM argument *B-3 
FNM keyword 

for specifying FAB$L_FNA and FAB$B_FNS 
fields from VAX MACRO *5-11 
FNS argument *B-5 
FORTRAN carriage control option 
See FAB$V_FTN option 
FORTRAN carriage control option list *5-24 
Free service*RMS-45 

condition values*RMS-46 

control block input and output fields*RMS-46 
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$GET macro 

program example *4-16 
Get option 

See FAB$V_GET option 


Get service*RMS-47, RMS-53 
applicable access modes*RMS-48 
condition values*RMS-53 

See also Completion status codes 
control block Input fields*RMS-50 
control block output fields*RMS-53 
requirement for user record area * RMS-50 
returning terminator character for terminal 
Input* RMS-49 

return status for various file access methods* 
RMS-7 

using input from mailbox devices*RMS-50 
using stream input*RMS-48 
using terminal input*RMS-48 
using the RAB$L_STV field for additional status 
information* RMS-50 
Get sharing option 

See FAB$V_GET sharing option 
Global buffer *5-19 

determining number of *5-20 
Global buffer count field 
See FAB$W_GBC field 
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HDR1 labels 

accessing from XAB$B_MTACC field* 14-5 
Highest virtual block field 
See XAB$L_HBK field 
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I/O mode 

how to switch for sequential files *4-24 
procedure for delaying decision until stream 
connection* 4-24 
when mode switching allowed *4-24 
Index bucket area number (IAN) 
program example *4-8 
Index bucket area number field 
See XAB$B_IAN field 
Index bucket fill size (IFL) 
program example *4-8 
Index bucket fill size field 
See XAB$W_IFL field 
Index bucket size field 
See XAB$B_IBS field 
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Indexed file 

block allocation *8-3 

bucket size for multiple areas •RMS-15 

composition • RMS-18 

creating •RMS-18 

creating with multiple-key • 4-5 

default bucket size • 5-3 

determinating key value •RMS-48 

determining keys and areas • 17-1 

determining key size • 7-4 

determining maximum record size • 5-21 

determining number of buffers • 7-6 

establishing index •RMS-7 

example of processing duplicate keys • 7-8 

example of specifying • 3-5 

fast delete option • 7-15 

Identifying data area • 13-4 

Inhibiting index update • 13-12 

initial extent quantity • 5-3 

inserting records with Put service • RMS-71 

invoking Get and Find services for • 7-4 

key of reference • 7-3 

methods of accessing records • 7-5 

options • 7-10 

positioning area • 8-7 

PROLOG selection •RMS-19 

restriction against VFC format • 5-18 

restriction to changing primary key •RMS-100 

separating index levels • 13-11 

setting bucket size • 5-4 

size of data bucket • 13-4 

specifying bucket size • 8-5 

specifying index area^ 13-10 

specifying Index bucket size^ 13-10 

string key options • 13-8 

update-if option • 7-17 

use of areas In • 4-8 

use of end-of-file option •RMS-7 

verifying sort order •RMS-7 

with allocation optionees-14 

with collating sequences • 13-3 

with deferred-write option •RMS-12 

with Get service • RMS-48 

with XABKEY^ 13-1 

Index level 

comparing primary key and alternate keys^ 
13-10 

Initialization macro 

advantages described • 3-7 
example • 3-5 
functions • 3-1 


Initialization macro (cont'd.) 
multiple bit fields3-5 
placement guidelines • 3-7 
using •3-6 
Inserting record 

program example • 4-16 
Internal file Identifier field 
See FAB$W_IFI field 
Internal stream Identifier field 
See RAB$W_ISI field 
IO$M_NOW modifier 

for Get and Put services • 7-14 
Item list^ 18-1 

guidelines for supplying • 18-1 
Item list address field 

See XAB$L_ITEMLIST field 
See XAB$L_ITMLST field 
Item list extended address block 
See XABITM block 
Item list length field 

See XAB$W_ITMLST_LEN field 
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Journaling extended address block 
See XABJNL block 


K 


Key 

defining as simple or segmented • 13-13 
determining match method • 7-5 
example of finding and deleting a record • 4-20 
example of updating a record • 4-21 
selecting path • 4-12 
size restriction for string type^ 13-15 
types of matches • 7-5 
Key buffer address field 
See RAB$L_KBF field 
Key definition extended address block 
See XABKEY block 
Key greater than 

See RAB$V_NXT option 
Key greater than or equal 
See RAB$V_EQNXT option 
Key name buffer address field 
See XAB$L_KNM field 
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Key of reference 

establishing • RMS-48 
Key of reference field 
See RAB$B_KRF field 
See XAB$_REF field 
Key option 

comparing primary and alternate keys* 13-8 
Key options flag field 
See XAB$B_FLG field 
Key position field 

See XAB$W_POSO through XAB$W_POS7 
field 

Key size field 

See RAB$B_KSZ field 

See XAB$B_SIZO through XAB$B_SIZ7 field 
Key string buffer 

program example *4-16 
Key string descriptor 
program example *4-16 
Key string length 

program example *4-16 
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Length field 

using to Indicate constant (keyword) value *2-4 
using to Indicate mask or bit offset *2-3 
Level of root bucket field 
See XAB$B_LVL field 
LIB$GET_INPUT 

example of use in program *4-12 
LIB$PUT_OUTPUT 

example of use In program *4-12 
LIBSSIGNAL (or LIB$STOP) 
using to signal errors *2-6 
Limit option 

See RAB$V_LIM option 
Load option 

See RAB$V_LOA option 
Locate mode 

comparing with move mode for buffer handling* 
7-15 

Locate mode option 

See RAB$V_LOC option 
Location field in XABALL 
See XAB$L_LOC field 
Lock record for read option 
See RAB$V_REA option 


Lock record for write option 
See RAB$V_RLK 
Logical name translation 

requirements for parsing *4-9 
Logical name translation access mode subfield 
See FAB$V_LNM_MODE subfield 
Longest record length field 
See XAB$W_LRL field 
Lowest level of index area number field 
See XAB$B_LAN field 
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Macro 

applicable VAX MACRO syntax rules *3-5 
arguments for service completion routines* 
3-11 

capabilities listed *4-1 
control block initialization *3-1 
library location *3-2 
names and control blocks *3-2 
naming conventions *3-2 
rules applicable to programming *3-6 
service *3-1 
using *3-6 
Macro field 

example of initializing *3-5 
setting at run time *3-5 
Magnetic tape accessibility field 
See XAB$B_MTACC field 
Manual unlock option 
See RAB$V_ULK option 
MAXBUF system parameter 

limiting size of user's ACL buffer* 14-3 
Maximum record number field 
See FAB$L_MRN field 
Maximum record size 

default value for remote file access *5-22 
Maximum record size field 
See FAB$W_MRS field 
Maximum record size field in XABFHC 
See XAB$W_MRZ field 
Maximum version option 
See FAB$V_MXV option 
Minimum record length field 
See also XAB$W_MRL field 
In XABKEY* 13-12 
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Mixed I/O 

precautions listed *4-24 
Mode field in XABITM 
See XAB$L_MODE field 
Mode switching 

when permitted • 4-24 
Multiblock count field 
See RAB$B_MBC field 
Multibuffer count field 
See RAB$B_MBF field 
Multinational Character Set 

See DEC Multinational Character Set 
Multiple argument 

delimiting in control block fields *3-5, 3-7 
specifying In control block fields •B-3 
Multiple key 

example of use with Close service *4-12 
performance cost of using* 13-14 
recommended number* 13-14 
Multiple-key indexed file 
creating *4-5 
Multiple record stream 
with block 1/0*4-25 
Multistream access option 
See FAB$V_MSE option 
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NAM$B_BID field *6-4 
NAM$B_BLN field *6-4 
NAM$B_DEV descriptor *6-3 
NAM$B_DEV field *6-4 
NAM$B_DIR descriptor *6-3 
NAM$B_DIR field*6-5 
NAM$B_ESL field *6-5 
NAM$B_ESS field *6-5 
NAM$B_NAME descriptor*6-3 
NAM$B_NAME field *6-7 
NAM$B_NODE descriptor*6-3 
NAM$B_NODE field *6-7 
NAM$B_NOP field *6-7 
options listed * 6-8 
NAM$B_RSL field *6-9, RMS-63 
NAM$B_RSS field *6-9 
NAM$B_TYPE descriptor*6-3 
NAM$B_TYPE field *6-9 
NAM$B_VER descriptor *6-3 
NAM$B_VER field *6-10 
NAM$I_DEV descriptor *6-3 


NAM$L_DEV field *6-4 

NAM$L_DIR descriptor*6-3 

NAM$L_DIR field *6-5 

NAM$L_ESA field *6-5 

NAM$L_FNB field *6-6, RMS-63, RMS-87 

NAM$I_FNB status bit 

listing *6-6 

NAM$I_NAME descriptor *6-3 

N AM$L _NAME field * 6-7 

NAM$I_NODE descriptor *6-3 

NAM$L_N0DE field *6-7 
NAM$L_RLF field *6-8 
NAM$L_RSA field *6-9, RMS-63 

NAM$I_TYPE descriptor *6-3 

NAM$L_TYPE field *6-9 

NAM$I_VER descriptor *6-3 

NAM$L_VER field *6-10 
NAM$L_WCC field *6-10 

returned by Remove service * RMS-82 
NAM$T_DVI field *6-5 
NAM$V_CNCL_DEV bit *6-6 
NAM$V_CONCEAL field*RMS-26, RMS-63 
NAM$V_DIR_LVLS bit *6-6 
NAM$V_EXP_DEV bit *6-6 
NAM$V_EXP_DIR bit *6-6 
NAM$V_EXR_NAME bit *6-6 
NAM$V_EXR_TYPE bit *6-6 
NAM$V_EXP_VER bit *6-6 
NAM$V_GRP_MBR bit *6-6 
NAM$V_HIGHVER bit *6-6 
NAM$V_LOWVER bit *6-6 
NAM$V_NOCONCEAL option *6-8, RMS-16, 
RMS-68 

NAM$V_NODE bit *6-6 
NAM$V_PPF bit *6-6 

NAM$V_PWD field*RMS-26, RMS-63, RMS-68 
NAM$V_PWD option *6-8, RMS-16 
NAM$V_QUOTED bit *6-6 
NAM$V_ROOT_DIR bit *6-7 
NAMSV_SEARCH _LIST bit *6-7 
NAM$V_SRCHXABS option *6-8 
NAM$V_SYNCHK option *6-8, RMS-68 
use with Parse service * 5-7 
using for Parse service without I/O*RMS-67 
NAM$V_WILDCARD bit *6-7 
NAM$V_WILD_GRP bit *6-7 
NAM$V_WILD_MBR bit *6-7 
NAM$V_WILD_NAME bit *6-7 
N AM$V_WILD_SFD 1 bit * 6-7 
NAM$V_WILD_TYPE bit *6-7 
NAM$V_WILD_UFD bit *6-7 
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NAM$V_WILD_VER bit*6-7 
NAM$W_DID field *6-4 
NAM$W_FID field *6-6 
NAM (name block) 

summary of fields •6-1 
using from higher-level language *6-2 
using from VAX MACRO *6-2 
NAM (name block) option 
See FAB$V_NAM option 
Name block 
See NAM 

Name block address field 
See FAB$L_NAM field 
Name block options field 
See NAM$B_NOP field 
Naming convention 
macros •3-2 
services • 3-3 
$NAM macro •B-G 

argument categories •B-S 
$NAM_STORE macro•B-? 
argument categories • B-7 
comparing with $NAM macros B-7 
NAM$T_DVI argument •B-7 
NAM$W_DID argument •B-7 
NAM$W_FID argument •B-7 
requirements •B-7 
NBP (next block pointer) 

default for block transfer • 7-2 
for block I/O •4-25 
functions listed • 4-25 
NETWORK_BLOCK_COUNT qualifier 

for specifying maximum record size • 5-22 
Next block pointer 
See NBP 
Next key 

See RAB$V_NXT option 
Next or equal key option 
See RAB$V_EQNXT option 
Next Volume service • RMS-55 
condition values •RMS-57 
control block input and output fields • RMS-56 
flush logics RMS-56 
input logic sequence • RMS-56 
output logic sequence • RMS-56 
requirements for usings RMS-56 
Node name address descriptor 
See NAM$L_NODE descriptor 
Node name address field 
See NAM$L_NODE field 


Node name length field 
See NAM$B_NODE field 
Node name size descriptor 

See NAM$B_NODE descriptor 
No lock option 

See RAB$V_NLK option 
Nonexistent record option 
See RAB$V_NXR option 
Non-flle-structured option 
See FAB$V_NFS option 
NOP field 

specifying multiple values •B-G 
No sharing option 

See FAB$V_NIL option 
Not end-of-flle option 
See FAB$V_NEF option 
Null character field 

See XAB$B_NUL field 
Number of allocation areas field 
See XAB$B_NOA field 
Number of key segments field 
See XAB$B_NSG field 
Number of keys field 
See XAB$B_NOK field 
Number sign (#) 

requirement for in control store macros3-8 
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$OPEN macro 

expansion of • 3-10 
for invoking the open service •4-1 
using in example^3-10, 3-11 
Open service •RMS-58 
condition values •RMS-64 
contrasted with Parse and Search services • 
4-10 

control block input fields • RMS-59 
control block output fields • RMS-61 
function • 4-1 
invoking • 4-4 
NAM input fields • RMS-63 
NAM output fields • RMS-63 
program example • 4-2 
requirements for usings RMS-59 
Option 

specifying by symbolic bit offset • 2-3 
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Optional argument 
to service •3-11 
Output file parse option 
See FAB$V_OFP option 
Output record buffer address field 
See RAB$L_RBF field 


p 


Packed decimal byte J 

structure for key type • 13-6 
Packed decimal string 
as key type* 13-6 
SPARSE macro 

for processing wildcard characters *4-10 
Parse service*RMS-66, RMS-67 
condition values*RMS-69 
control block Input fields*RMS-67 
control block output fields*RMS-68 
preparing for file search * 4-9 
preparing for wildcard character processing * 
RMS-67 

program example *4-9 
requirements for using*RMS-67 
Path to file 

file specification string address *4-9 
file specification string size *4-9 
Performance 

improving with SHR argument *4-14 
Print format option 

See FAB$V_PRN option 

Print format options for VFC records with 2-byte 
control area * 5-25 
Program 

using wildcard characters *4-12 
Program execution mode 
using to call services *2-7 
Program Interface *2-1 
Programming language 

using control blocks with *2-1 
Programming rules *3-6 
Prolog field 

See XAB$B_PROLOG field 
Prolog level * RMS-18 
Prolog version number field 
See XAB$W_PVN field 
Prompt buffer address field 
See RAB$L_PBF field 


Prompt buffer size field 
See RAB$B_PSZ field 
Prompt option 

See RAB$V_PMT option 
Protection extended address block 
See XABPRO block 
Purge type-ahead option 
See RAB$V_PTA option 
$PUT macro 

program example *4-16 
Put service*RMS-70 

condition values*RMS-74 

See also Completion status codes 
control block Input fields*RMS-73 
control block output fields*RMS-74 
inserting records by sort order*RMS-72 
inserting records into indexed files*RMS-71 
inserting records into relative files*RMS-71 
inserting records Into sequential files*RMS-71 
inserting records with duplicate keys*RMS-72 
record locking caution*RMS-72 
record-processing options *7-16 
requirements for using*RMS-72 
update-lf logic*RMS-72 
using RAB$V_TPT option*RMS-71 
using RAB$V_UIF option * RMS-71 
using with mailboxes*RMS-71 
using with stream format files*RMS-71 
Put service option 

See FAB$V_PUT option 
Put sharing option 

See FAB$V_PUT sharing option 


R 


RO 

use by control block store macros *3-8 
use in asynchronous operations *2-5 
RAB (record access block) 
summary of fields * 7-1 
RAB$B_BID field *7-2 
RAB$B_BLN field *7-3 
RAB$B_KRF field *7-4 

for selecting key path *4-12 
for various services * 7-4 
RAB$B_KSZ field *7-4 
DECnet requirement * 7-4 
key size compared to data types *7-4 
shared offset *7-4 
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RAB$B_KSZ field (cont'd.) 
use with limit option •7-13 
use with search key *7-12, 7-14 
RAB$B_MBC field •7-5 
default logic •7-5 
performance benefit •7-6 
use restriction • 7-5, 7-6 
RAB$B_MBF field •7-6 
default logics7-6 
performance benefit • 7-6 
use restriction • 7-6 
use with read-ahead option • 7-16 
use with write-behind option • 7-16 
values for various organizations • 7-6 
RAB$B_PSZ fields7-7 
shared offset • 7-7 
RAB$B_RAC fields7-7 
options • 7-7 
use restriction • 7-7 
RAB$B_TMO field 

use with RAB$V_TMO option for mailbox 
service • 7-14 
RAB$B_TMO fields7-21 

for various record functions • 7-21 
requirement for RAB$V_TMO option • 7-21 
use with timeout option for terminal operation • 
7-19 

RAB$C_KEY option • 7-8 
RAB$C_RFA option •7-8 
RAB$C_SEQ option • 7-7 
RAB$L_BKT field 
as output • 7-2 
use with block I/O • 7-2 
RAB$L_CTX field •7-3 
RAB$L_FAB fields7-3 
RAB$L_KBF fields7-3 
shared offset • 7-3 
use with limit option •7-13 
use with RAB$B_KSZ field • 7-4 
use with search key • 7-12, 7-14 
RAB$L_PBF fields7-7 

requirement for carriage control •7-7 
RAB$L_RBF field •4-4, 7-8 
RAB$L_RHB field •7-9 

buffer size compatibility with FAB$B_FSZ^ 7-9 
default logics7-9 
use by various services • 7-9 
use restriction • 7-9 
RAB$L_ROP fields7-10 
options listed • 7-10 
specifying key match method • 7-5 


RAB$L_STS fields7-20 
RAB$L_STV0 field 

for returning terminating character •RMS-49 
RAB$L_STV fields7-20 
alternate access to • 7-20 
for returning I/O status block •RMS-49 
for returning I/O status block from Put service • 
RMS-74 

for returning PID from Put service •RMS-71 
for returning process identification (PID)^ 
RMS-50 

for returning record length • RMS-53 
using with Get service •RMS-50 
RAB$L_UBF fields7-21 
buffer logics7-21 
RAB$L_XAB fields7-22 

requirement for using XABTRM^ 18-1 
RAB$V_ASY option • 7-11, 7-14 
use restriction • 7-15 
RAB$V_BIO option • 7-11 
RAB$V_CC0 option • 7-18 
RAB$V_CVT option • 7-19 
RAB$V_E0F option • 7-12 
RAB$V_EQNXT option • 7-12 
examples • 7-13 

specifying key match method • 7-5 
RAB$V_ETO option 

requirement for using XABTRM^ 18-1 
RAB$V_FDL option • 7-15 
use restriction • 7-15 
RAB$V_KGE option 

See RAB$V_EQNXT option 
See RAB$V_NXT option 
RAB$V_LIM option • 7-13 
RAB$V_LOA option • 7-13 
determining fill size^ 13-10 
example of use • 4-8 
use restriction • 13-4, 13-11 
RAB$V_LOC option • 7-15 
use restriction • 7-15 
RAB$V_NLK option • 7-17 

precedence over RAB$V_ULK option • 7-17 
RAB$V_NXR option • 7-17 

output from Get service • 7-17 
relevant completion codes • 7-17 
use restriction • 7-17 
RAB$V_NXT option • 7-14 
examples • 7-14 

specifying key match method • 7-5 
RAB$V_PMT option • 7-19 
RAB$V_PTA option • 7-19 
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RAB$V_RAH option*7-12, 7-15 
default logic*7“ 16 
use restriction *7-16 
RAB$V_REA option *7-17 
use restriction *7-17 
RAB$V_RLK option *7-18 

precedence over RAB$V_REA option *7-18 
RAB$V_RNE option *7-19 
RAB$V_RNF option *7-19 
RAB$V_RRL option *7-18 
RAB$V_SYNCSTS optibn*7-16 
RAB$V_TMO option 

for immediate mailbox service *7-14 
RAB$V_TMO option *7-14, 7-18, 7-19 
RAB$V_TPT option *7-16 
use restriction *7-16 
using with Put service*RMS-71 
RAB$V_UIF option *7-17 
effects on Put service *7-17 
use restriction for indexed files *7-17 
using with Put service*RMS-71 
RAB$V_ULK option *7-18 

subordinate to RAB$V_NLK option *7-18 
RAB$V_WAT option *7-18, 7-19 
precedence over other options *7-19 
use with the RAB$V_TMO option *7-18 
RAB$V_WBH option *7-12, 7-16 
default logic *7-16 
use restriction *7-16 
RAB$W_ISI field *7-3 
RAB$W_RFA field *7-9 

additional symbolic offsets *7-9 
as argument to $RAB_STORE macro *B-12 
example *7-9 
guidelines for using *7-9 
RAB$W_RSZ field *4-4, 7-20 
for various services*7-20 
operational notes listed * 7-20 
RAB$W_STV0 offset 

alternate access to RAB$L_STV* 7-20 
RAB$W_STV2 field 

for returning length of escape sequence* 
RMS-49 

RAB$W_STV2 offset 

alternate access to RAB$I_STV*7-20 

RAB$W_USZ field *7-21 
recommended value *7-21 
use with block 1/0*7-22 
RAB$_V^WAT option 

use with timeout option for record locking * 
7-18 


RAB (record access block) 
arguments* 1-4 

described In context of example *4-4 
description* 1-4 
general description*7-1 
summary of fields *7-1 
$RAB macro *B-9 

argument categories *B-10 
$RAB_STORE macro *B-11 
argument categories *B-12 
comparing with $RAB macro *B-11 
requirements * B-12 
RFA argument *B-12 
RDT (revision-date-time) argument *B-16 
Read ahead option 

See RAB$V_RAH option 
Read check option 

See FAB$V_RCK option 
Read-no-echo option 
See RAB$V_RNE option 
Read no filter option 

See RAB$V_RNF option 
Read regardless of lock option 
See RAB$V_RRL option 
Read service*RMS-76 
condition values*RMS-78 
control block input fields*RMS-77 
control block output fields*RMS-77 
requirements for using*RMS-77 
Record 

formats* 1-1 

requirements for reading or writing in a file 
4-12 

Record access block 
See RAB 

Record access field 
See RAB$B_RAC field 
Record attribute field 
See FAB$B_RAT field 
Record attributes field in XABFHC 
See XAB$B_ATR field 
Record buffer field 
See RAB$L_RBF field 
Record file address field 
See RAB$W_RFA field 
Record format field 
See FAB$B_RFM field 
Record header buffer field 
See RAB$L_RHB field 
Record I/O 

how to execute * 4-24 
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Record locking record-processing options*7-17 
Record-processing 
services listed *3-3 
Record-processing macro 
format example •3-12 
Record-processing option 
for Connect service *7-10 
Record'processing options field 
See RAB$L_ROP field 
Record size field 

See RAB$W_RSZ field 
Record stream 

in the context of a RAB*7-1 
Recovery unit extended address block 
See XABRU block 
Recovery unit XAB 
See XABRU block 
Register 

saving when making call *2-4 
Register 0 
See RO 

Related file identification field 
See XAB$W_RFI field 
Related file identification field in XABALL 
See XAB$W_RFI field 
Related file NAM block address field 
See NAM$L_RLF field 
Relative file 

buffer requirement *7-6 
defining cell size *5-21 
description of relative record number *7-5 
determining record length *5-21 
establishing highest record number *5-21 
nonexistent record processing*7-17 
omitting initial prezeroing *4-23 
random access *7-3 
record size limit *5-21 
RFA value *7-9 
specifying bucket size *8-5 
specifying cell size* 10-5 
Relative file field 
record access *7-2 
Relative volume number field 
See XAB$W_VOL field 
Release service*RMS-79, RMS-80 
condition values*RMS-80 
control block input and output fields*RMS-80 
Remove service*RMS-81, RMS-82 

caution against mixing with Search service* 
RMS-82 

comparing with Erase service*RMS-82 


Remove service (cont'd.) 
condition values*RMS-84 
control block Input fields*RMS-82 
control block output fields*RMS-83 
Improving performance*RMS-82 
requirements for using*RMS-82 
use with wildcard characters and search lists* 
RMS-82 

Rename service*RMS-85, RMS-86 
alternative to specifying arguments to 
SRENAME macro* RMS-86 
condition values*RMS-88 
control block input fields*RMS-86 
control block output fields*RMS-87 
exception in argument list *2-5 
format *3-11 

Indicating successful completion *4-16 
program example *4-14 
requirements for using*RMS-86 
Reserved event flag 
use of *2-7 
Restriction 

to calling services *2-7 
Resultant string 
requesting *6-2 

Resultant string area address field 
See NAM$L_RSA field 
Resultant string area size field 
See NAM$B_RSS field 
Resultant string length field 
See NAM$B_RSL field 
Retrieval window size field 
See FAB$B_RTV field 
Retrieving record 

program example *4-16 
Revision date and time extended address block 
See XABRDT block 
Revision date and time field 
See XAB$Q_RDT field 
Revision number field 
See XAB$W_RVN field 
Rewind on close option 
See FAB$V_RWC option 
Rewind on open option 
See FAB$V_RWO option 
Rewind service*RMS-89, RMS-90 
condition values*RMS-90 
control block input fields*RMS-90 
control block output fields*RMS-90 
use restriction * RMS-90 
RMS$_OK_LIM success status code *7-13 
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RMS-11 

block identifier field limitation*5-3 
$RMSDEF macro 

access to symbolic offset names *2-2 
RMS_DFNBC system parameter 

for specifying default network block count* 
5-22 

Root index bucket virtual block field 
See XAB$L_RVB field 
Run-time 

access options* 1-2 
implementation of services *4-1 
information* 1-4 
processing environment *2-1 
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Search 

synonyms* 7-12 
Search list 

as alternative to using wildcard characters* 
4-10 

using with Remove service*RMS-82 
$SEARCH macro 

for processing wildcard characters *4-10 
Search service*RMS-91, RMS-92 
condition values*RMS-94 
control block input fields*RMS-92 
control block output fields*RMS-93 
example of completion code handling *4-12 
program example *4-9 
requirement for Parse service *4-9 
using with wildcard characters and search lists* 
RMS-92 

Search string translation 

requirements for parsing *4-9 
Secondary device characteristics field 
See FAB$L_SDC field 
Segmented key* 13-13 

restriction against overlapping* 13-13 
Separator 

in symbolic name *2-3 
Sequential only option 
See FAB$V_SQO option 
Service 

allowable program execution modes *2-7 
block I/O *3-5 
calling example *3-11 
invoking at run time *3-1 


Service (cont'd.) 

naming conventions *3-3 
passing argument list to *3-10 
Service macro 
description *3-1 

for creating and processing files *4-1 
format *3-10, 3-11 
format rules *3-11 
types *3-12 
Services 

restrictions to calling *2-7 
SET FILE command 

for changing global buffer count value *5-19 
SET RMS_DEFAULT command *7-6 
to limit default extension quantity *5-6 
Set system failure exception mode 
See SYSSSETSFM 
Severity code 

in completion status code field * 2-6 
S field in symbolic offset 

for specifying field length * 2-3 
Shared access 

requirement to specify *4-1 
Shared file 

end-of-flle positioning*RMS-7 
SHR field 

See FAB$B_SHR field 
Sign representation 

preference for key type coding* 13-7 
Simple key* 13-13 
Sort order 

establishing *7-5 
Space service*RMS-95 
condition values*RMS-96 
control block input fields*RMS-96 
control block output fields*RMS-96 
Spool file option 

See FAB$V_SPL option 
Starting logical block number field 
See XAB$L_SBN field 
Stream record format option 
See FAB$C_STM option 
Stream record format with carriage return option 
See FAB$C_STMCR option 
Stream record format with line feed option 
See FAB$C_STMLF option 
STS (status) field 

See also Completion status field 
See also FAB$L_STV field 
contents *2-6 
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STV (status value) field 

See also Completion status value field 
contents •2-6 
Submit command file option 
See FAB$V_SCF option 
Success completion routine •2-5 
Summary extended address block 
See XABSUM block 
Summary XAB 

for key Information • 13-1 
Supersede existing file option 
See FAB$V_SUP option 
Supervisor-mode (PSL$C_SUPER) constant 
for FAB$V_CHAN_MODE^5-5 
Symbol definition macro 
description • 3-1 
usings 3-7 
Symbolic address 

use in locating start of control blocks3-7 
Symbolic bit offset 

use in specifying options • 2-3 
Symbolic naming exception 
control blocks2-3 
Symbolic offset 
control blocks2-4 
format • 2-2 

use in locating control block fields • 2-2 
Synchronous status option 
See FAB$V_SYNCSTS option 
See RAB$V_SYNCSTS option 
SYS$BINTIM^3-10 
SYSSCLOSE 

See Close service 
SYSSCONNECT 

See Connect service 
SYSSCREATE 

See Create service 
SYSSDELETE 

See Delete service 
SYS$DISCONNECT 

See Disconnect service 
SYS$DISPLAY 

See Display service 
SYSSENTER 

See Enter service 
SYS$ERASE 

See Erase service 
SYSSEXTEND 

See Extend service 


SYS$FIND 

See Find service 
SYS$FLUSH 

See Flush service 
SYSSFREE 

See Free service 
SYSSGET 

See Get service 
SYS$LIBRARY:STARLET.MLB 
as source of macros • 1-1 
SYSSNXTVOL 

See Next Volume service 
SYS$OPEN 

See Open service 
SYS$PARSE 

See Parse service 
SYS$PUT 

See Put service 
SYS$QIO 

for additional processings5-18 
use in I/O operation • 2-7 
SYSSREAD 

See Read service 
SYS$RELEASE 

See Release service 
SYSSREMOVE 

See Remove service 
SYSSRENAME 

See Rename service 
noting format differences3-11 
SYS$REWIND 

See Rewind service 
SYS$SEARCH 

See Search service 
SYS$SETSFM 

use in signaling errors •2-6 
SYS$SPACE 

See Space service 
SYS$TRUNCATE 
See Truncate service 
SYSSUPDATE 

See Update service 
SYSSWAIT 

See Walt service 
SYS$WRITE 

See Write service 
SYSPRV privilege 

requirement for creating files with different UlCs 
14-8 
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System service exception • 2-6 
System service exception generation 
disabling *2-6 


T 


Temporary file delete option 
See FAB$V_TMD option 
Temporary file option 
See FAB$V_TMP option 
Terminal device record-processing option *7-18 
Terminal extended address block 
See XABTRM block 
Terminal read operation 

RAB$I_ROP field options* 18-2 

T field in symbolic offset 

for specifying varying field length *2-3 
Timeout field 

See RAB$B_TMO field 
Timeout option 

See RAB$V_TMO option 
Total key size field 
See XAB$B_TKS field 
Truncate at end-of-file option 
See FAB$V_TEF option 
Truncate-on-put option 
See RAB$V_TPT option 
Truncate option 

See FAB$V_TRN option 
Truncate service •RMS-97 
condition values*RMS-98 

See also Completion status codes 
control block input fields*RMS-98 
control block output fields*RMS-98 
use restriction*RMS-97 
Type code field in allocation XAB 
See XAB$B_COD field 
Type code field In date and time XAB 
See XAB$B_COD field 

Type code field In file header characteristics XAB 
See XAB$B_COD field 
Type code field in item list XAB 
See XAB$B_COD field 
Type code field in key XAB 
See XAB$B_COD field 
Type code field in protection XAB 
See XAB$B_COD field 


Type code field In revision date and time XAB 
See XAB$B_COD field 
Type code field in summary XAB 
See XAB$B_COD field 
Type code field in terminal XAB 
See XAB$B_COD field 
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UlC (user Identification code) 

delimiting in control block fields *3-7 
Undefined record format option 
See FAB$C_UDF option 
Update-if option 

See RAB$V_UIF option 
Update service*RMS-99, RMS-100 

comparing with Put service for stream format 
files* RMS-100 
condition values*RMS-101 
control block input fields*RMS-100 
control block output fields*RMS-101 
invoking* 5-11 
program example *4-20 
requirements for using*RMS-100 
using with Indexed files*RMS-100 
Update sharing option 
See FAB$V_UPD option 
User context field 

See RAB$L_CTX field 
User-entered reply 

as used in example for selecting key path *4-12 
User file-open option 
See FAB$V_UFO option 
User identification code field 
See XAB$L_UIC field 
User-mode (PSL$C_USER) constant 
for FAB$V_CHAN_MODE*5-5 
User process Interlock option 
See FAB$V_UPI option 
User prompt string 

program example *4-16 
User record buffer address field 
See RAB$L-_UBF field 
User record buffer size field 
See RAB$W_USZ field 
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Variable-length format option 
See FAB$C_VAR option 
Variable-length record 

guidelines for specifying*5-21 
VAX language 

use with control blocks *2-1 
VAX MACRO 
See Macro 

VAX Procedure and Condition Handling Standard 
for calling services *3-3 
VFC record format option 
See FAB$C_VFC option 
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$WAIT macro 

format difference *3-12 
Wait option 

See RAB$V_WAT option 
Wait service •RMS-102 
condition values •RMS-103 
control block input and output fields*RMS-102 
Wildcard character 

use with Remove service*RMS-82 
use with Search service *4-10 
Wildcard context field 
See NAM$L_WCC field 
Wildcard substitution 

specifying NAM$L_RSA field *6-9 
Write-behind option 

See RAB$V_WBH option 
Write check option 

See FAB$V_WCK option 
Write service*RMS-104, RMS-105 
condition values*RMS-106 
control block input fields*RMS-105 
control block output fields*RMS-105 
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XAB$B_AID field *8-2 
XAB$B_ALN field *8-2 


XAB$B_AOP field *8-3 
options *8-4 
XAB$B_ATR field *10-2 
options* 10-2 
XAB$B_BKZ field 
as output *8-5 
default logic *8-5 
determining bucket size *8-5 
In allocation XAB (XABALL)*8-4 
In file header characteristics allocation XAB 
(XABFHC)* 10-3 
RMS-11 restriction * 8-5 
size requirements for multiple index areas *8-5 
XAB$B_BLN field 

In allocation XAB (XABALL)*8-5 
In date and time XAB (XABDAT)*9-2 
In file header characteristics XAB (XABALL)* 
10-3 

in Item list XAB (XABITM)* 11-2 
in key XAB (XABKEY) * 13-2 
in protection XAB (XABPRO)* 14-4 
in revision date and time XAB (XABRDT)* 15-2 
In summary XAB (XABSUM)* 17-1 
in terminal XAB (XABTRM) * 18-2 
XAB$B_C0D field 
See also COD field 
in allocation XAB (XABALL) *8-5 
in date and time XAB (XABDAT)*9-3 
In file header characteristics XAB (XABFHC)* 
10-3 

in item list XAB (XABITM)* 11-2 
In key XAB (XABKEY)* 13-2 
in protection XAB (XABPRO)* 14-4 
In revision date and time XAB (XABRDT)* 15-2 
In summary XAB (XABSUM)* 17-1 
in terminal XAB (XABTRM)* 18-2 
XAB$B_DAN field* 13-4 
requirement for* 13-4 
XAB$B_DBS field *13-4 
XAB$B_DTP field *13-5 
data formats * 13-6 
data type restrictions* 13-5 
options* 13-5 

use with search key * 7-13, 7-14 
value prefixes for sorting* 13-5 
XAB$B_FLG field* 13-8, B-21 

option allowable combinations listed* 13-9 
options* 13-8 
XAB$B_HSZ field *10-4 
use restriction* 10-4 
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XAB$B_IAN field* 13-10 
conditional usage • 13-10 
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XAB$B_IBS field *13-10 
XAB$B_LAN field *13-11 
indicating index level *8-5 
relationship to XAB$B_AID field* 13-11 
requirement for compatibility with XAB$B_IAN 
field* 13-11 
use restriction* 13-11 
XAB$B_LVL field* 13-12 
XAB$B_MTACC field* 14-5 
default logic* 14-5 
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XAB$B_N0A field *17-2 
XAB$B_N0K field *17-2 
XAB$B_NSG field* 13-12 
XAB$B_NUL field *13-12 
use restrictions *13-12 
XAB$B_PROLOG field *13-13 
default logic* 13-13 
service usage* 13-13 
use restriction *13-13 
XAB$B_PROT_OPT field* 14-7 
XAB$B_RFO field *10-5 
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XAB$B_SIZ0 through XAB$B_SIZ7 field* 13-14 
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with simple key* 13-14 
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14-2 

handling ACE* 14-2 
XAB$L_ACLCTX field* 14-2, 14-3 
XAB$L_ACLSTS field* 14-3 
error handling guidelines* 14-3 
use restriction* 14-4 
XAB$L_ALQ*8-3 
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XAB$L_DVB field *13-7 
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comparing with FAB$L_ALQ field* 10-4 
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determining value *8-6 
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in XABALL*8-6 
inXABDAT*9-3 
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in XABKEY* 13-12 
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in XABRDT*15-2 
in XABSUM*17-2 
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setting XAB$W_GRP field* 14-4 
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XAB$V_CHG option* 13-8 
use restriction* 13-8 
XAB$V_CR option* 10-2 
XAB$V_CTG option *8-4 
XAB$V_DAT_NCI\/IPR option* 13-8 
XAB$V_DUP option* 13-8 
XAB$V_FTN option* 10-2 
XAB$V_HRD option *8-4 
use restrictions *8-4 
XAB$V_IDX_NCMPR option* 13-8 
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with XAB$B_NUL field* 13-9 
XAB$V_0NC option * 8-4 
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limitation* 14-3 
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limitations imposed by MAXBUF* 14-3 
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14-3 

XAB$W_DEQ field *8-6 
XAB$W_DFL field *13-4 
advantages of using* 13-4 
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determining value* 13-4 
use with RAB$V_L0A option *7-13 
XAB$W_DXQ field in XABFHC* 10-3 
XAB$W_FFB field *10-4 
XAB$W_GBC field in XABFHC* 10-4 
XAB$W_GRP field *14-4 
XAB$W_IFL field *13-10 
advantages of using* 13-11 
XAB$W_ITMLST_LEN field* 18-2 

requirement for valid terminal driver* 18-1 
XAB$W_LRL field* 10-4 
use restriction* 10-5 
XAB$W_MBM field* 14-5 
XAB$W_MRL field *13-12 

comparing primary key and alternate keys* 
13-12 


XAB$W_MRZ field in XABFHC* 10-5 
determining value* 10-5 
XAB$W_POSO through XAB$W_POS7 field* 
13-12 

requirement to be compatible with XAB$B_ 
SIZO through XAB$B_SIZ7 field* 13-13 
XAB$W_PRO field* 14-6 
default logic* 14-7 
organization* 14-6 
required ordering of arguments* 14-6 
subfield offsets* 14-6 
user classes* 14-7 
XAB$W_PVN field* 17-2 
XAB$W_RFI field *8-7 

as argument to $XABALI_STORE macro* 

B-14 

requirement for XAB$C_RFI*8-7 
specifying *8-7 

XAB$W_RVN field *9-3, 15-3 
XAB$W_VERLIMIT field in XABFHC* 10-6 
XAB$W_VOL field *8-7 
use restriction * 8-7 
XAB$_REF field* 13-14 
XAB (extended attribute block) 
description* 1-3 

naming conventions for FAB* 1-3 
naming conventions for RAB* 1-4 
program example *4-8 
types* 1-3 

XABALL block* 1-3, 8-1 

relationship to FAB fields *8-1 
summary of fields * 8-1 
$XABALL macro *B-13 
argument categories *B-13 
$XABALL_STORE macro*B-14 
argument categories*B-14 
comparing with $XABALL macro*B-14 
requirements * B-14 
XABDAT block *9-1 
brief description* 1-3 
summary of fields * 9-1 
value selection logic * 9-2 
$XABDAT macro *B-15 
$XABDAT_STORE macro *B-16 
argument categories *B-16 
argument variations *B-16 
example of use *3-9 
requirements * B-16 
XABFHC block* 10-1 
brief description* 1-3 
summary of fields* 10-1 
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XABFHC block (cont'd.) 
use exception* 10-1 
values for shared sequential files* 10-1 
$XABFHC macro *B-17 
$XABFHC_STORE macro *B-18 
argument categories *B-18 
requirements * B-18 
XABITM block* 11-1 
brief description* 1-3 
summary of fields* 11-1 
$XABITM macro *B-19 
XABJNL block* 12-1 
brief description* 1-3 
XABKEY block* 13-1 
brief description* 1-3 
data type options* 13-5 
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